Other Software > Developer's Corner

Documenting the Why not just the What

(1/2) > >>

mouser:
Even when I do a good job of documenting my code, I think one thing as a programmer I am often guilty of is failing to document bigger decisions about WHY we chose one approach instead of another.  Sometimes these are very high level decisions that we think we will never forget, but in time we do.. and it can lead to some real confusion eventually.

Today i spent 10 minutes trying to remember why i spent all this effort in some older code doing some text parsing client-side in javascript when it would seem so much more logical to do it server-side (in php or whatever).  I finally remembered that I actually did have a reason for it (I wanted this code to work both in a client-server mode, but also be available for building into a standalone embedded-javascript-engine desktop application).

Anyway, I just thought I would make a post to suggest that documenting the WHY of higher level decisions is an important aspect of documentation that we as coders shouldn't overlook.

Deozaan:
You mean like why it's better to use a constant that has a 16 character long name all over your code instead of just placing its value of 1 everywhere?

:P

(This is an inside joke/tease, since mouser, JoTo and I had this discussion in IRC last night.)

Renegade:
That's a good point. Comments can sometimes be terse.

I hate when I go back to something and I've not commented it, or been short. It's better to be verbose.

Ath:
This is indeed one of 'us developers' weak spots, that I have on my todo list of improving for this year 8) Hope others (at least in open/shared projects) also do that :tellme:

iphigenie:
It's something I learned and tell my devs: try to code -and document- to yourself in 2 years looking back

Picture yourself having to go back to the thing in 2 years, or even a year. Most likely, your future self will shake their head at the mess and quality of it. That is normal. You'll know better in two years, one hopes. But if your future self will tear their hair out and imagine their hands around your neck... well... document and/or refactor some more :)

In the fast moving, agile web world, often all you can do is document all the design debt you have accumulated in the product against future pain. But at least you can do that.

Navigation

[0] Message Index

[#] Next page