Tag: Edward Caissie

Some may say the code is the documentation … and others may reply with the documentation is the code. I believe both are true; and, more importantly, they are not mutually exclusive.

First off, the code quality should be (if possible) in a format that is easily (human) readable. The idea is to provide the person looking at the source code an easy-to-follow layout as well as providing sensible separations between the various code structures.

The code should also be semantically written using naming conventions that help explain why each code construct exists, as well as providing an appropriate indication of what the code will do.

The above two ideas do not preclude the requirement for document blocks to be also included as appropriate in the code, as well as additional code comments explaining specific details that may not be readily apparent from reading the code.

Essentially, the point of view I recommend with documentation is quite simple:

Imagine it is six months later and you did not write the code yourself. Does the documentation you provided properly explain the who, what, where, when , and why of the code? … because in six months time, if you have not been working with the code all along, it will likely be just like you never wrote the code in the first place. Now, imagine what another developer would be going through.

Good UX is not solely in the realm of the end-user.

Most importantly, write the inline documentation when developing the code. You will find it much easier to write the documentation while you develop the code versus going back after the fact and writing it then.

Also, I find it much easier to focus on the task at hand if I do the document framing (read: basic outline) prior to writing the first code structure. Ideally this will also provide the scope of the code as well.