General Musing

blaze your trail

5 Missteps in Writing Code

with 4 comments

Like most developers I am constantly struggling to deliver in the face of unrealistic or extremely tight deadline, which can be self imposed or come from external sources. As I will likely discuss in a future article this can be due to over optimism or rigid planning in the face of customer demand. It can also be due to missteps which the developer themselves have made.

Yet there is a light at the end of the tunnel, possible to produce the work without the need to resort to overtime. Below I’ve distilled the five missteps to avoid to allow a developer to focus on producing working code. All that’s needed is to avoid these simple to make missteps.

Misstep 1

Documenting too much of your code, or not documenting your code

Fully documented code is fantastic, it can really help you out. Whether you use java, php, c, or any other language you might rely on the API descriptions or man pages multiple times a day. So you may believe that your code needs to be as well documented, it doesn’t. And even if it does, it won’t be. Documentation like code gets stale, in fast changing environments such as code under full development it gets stale fast. After a simple refactor of code the documentation may no longer matches with the code. The same goes for not documenting the code, not having documentation will ensure that complicated code may become unclear with in a day of writing, for others and your future self.

What you should do is document the entry points and exit points of the code and the global flow of the program, any only document details when it is impossible to understand from the code itself. And documentation can be extended by not falling into misstep 2.

Misstep 2

Not Unit Testing

I often complain about the lack of unit tests for code, the real reason I have for writing unit tests is that I use them as stubs for my code. I can write once and deploy multiple times, by working test driven: writing the test first and the code second; you are making it possible to use the code you wrote for the unit test for the next piece of code you writing. When you start using more complex unit testing models such as with mock objects the amount of code you write for the unit test is minimal.

Misstep 3

Spending Development Time on Optimization

Code does not need to be optimized during the main development cycle, that doesn’t mean that you need to write bad code. It means that there in no need to attach a profiler during development. Naturally doing a regular research cycle to see whether on piece of code performs better than another is fine, this is aimed at improving your coding style. Doing this as a part of the development cycle slows the development cycle down.

Misstep 4

Not Allowing for Auditing

Syslog, log4j and other logging libraries allow for you to use different levels of logging, from debug to notices there can be 5 or more logging levels. It’s not necessary to use all of the log levels from emergency to debug and they can be useful in debugging issues for sysadmins and yourself at a later stage.

Misstep 5

Becoming too committed to the code or the methodology

I’ve written some beautiful code in the past, sometimes it was just too beautiful. It was esthetically pleasing and looked like it performed magic. I probably should have deleted it the moment I wrote it. The code, albeit good, was not excellent and until I let go of the emotional investment and pride I had I realized that it should be trashed.

The same goes for certain methodologies, how beautiful and elegant SCRUM, XP or anything else might be sometimes they are a square peg in a round hole. This doesn’t mean letting go of an entire methodology which brings great value, some intellectual rigour is required.

Image source: xt0ph3r


Written by Daniël W. Crompton (webhat)

July 18, 2012 at 8:06 am

4 Responses

Subscribe to comments with RSS.

  1. Point 2 is a mahor major major issue. Its often tempting not to unit test and get the whole software work as fast. But at the end the small errors in the units mix together adding possiblt errors in the interfaces and make a symphony of errors, which makes feel like the only way out of this may be shooting yourself on the head (talking of non commercial projects with one or very few persons). Unit testing is a damn important thing, although it may seem unnecessary at some points, but is a key step to construction of successful software as planned.


    July 18, 2012 at 12:17 pm

    • I mostly find that once somebody gets it they start using unit testing as their primary code and the application they are writing is merely the glue which binds the unit tests together. There is a power in the use of unit testing libraries in R&D, specifically the research side.

  2. For me the biggest issue is #1, when your reading through code that has light documentation on it, its much easier to understand what the developer was thinking when he or she wrote it. Its also easy for more junior level developers to look at the code and understand it if its commented.

Please Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: