My coding style

  1. I believe in self-documenting code (i.e. the code is the documentation, not the comments). My goal is to minimise the code reader from needing to look up additional material (documentation or whatever) aside from the code itself.

    This may make the code more verbose, but I think it is worth it (at least for me). Sometimes I work offline and happen to not have any other documentation aside from the source code itself.

  2. I believe in first-pass understandability. My goal is not just to make the code self-documenting or simple or readable, but to make the reader understand the code properly in the first pass of reading.

    (At worst, second reading.) I hate looking at my code months later and having to re-read it a few times before I could start maintaining it.

  3. Elegant code is not always the most self-documenting nor the most first-pass understandable code. Elegance is not my goal. My goal is to minimise the effort for code maintenance.

    I do not have the luxury to spend a lot of time doing coding, so if I can spend more time developing new things as opposed to maintaining an old code, then that would be nice.

  4. At the end of the day, coding and maintenance is all about getting the code to match explicitly documented behaviours and vice versa.

    Issues arise when the documentation does not explicitly match "all" code behaviours (e.g. bug vs. undocumented "feature") or the documentation is "misunderstood" (e.g. unclear documentation vs. it can be interpreted in several ways). And, yes, sometimes documentation does not even exist. C'est la vie.

    (By documentation here I mean not the code, obviously, but whatever specification or material that needs to co-exist with the code. Supposedly.)