Documenting the Why not just the What

[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?



(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 Hope others (at least in open/shared projects) also do that

[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.

[barney]

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

-iphigenie (April 10, 2011, 06:18 AM)

Hm-m-m ... thought it was just me  .  I've been chastised in the past - corporate world - for being overly verbose in code.  This, mind you, by fellas that could make neither head nor tail of code they'd written just six (6) months agone  .  External documentation is not my strong suit when it comes to apps I've created, but internal comments have been such that I could come back a decade later and know what - and sometimes the why of it - I'd done.  Thought it was standard practice  ?  Now I don't feel so bad about some of the Web stuff I've done recently ... seems I'm in popular/common, if not good, company  .

On a slightly different, hopefully related, note ... how much does it matter between having in-line documentation as opposed to external?  Yeah, the obvious bit about not having the separate document, but what else?  The relevance is that I'm showing someone else how to do some rather esoteric Web pages, and we have a constant battle over in-page comments ... she claims they slow loading time.  For that matter, what weight do comments in compiled code have, as opposed to pure code?  Is there really a significant trade-off  ?  Or is the reason just laziness?

[iphigenie]

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

-iphigenie (April 10, 2011, 06:18 AM)

Hm-m-m ... thought it was just me  .  I've been chastised in the past - corporate world - for being overly verbose in code.  This, mind you, by fellas that could make neither head nor tail of code they'd written just six (6) months agone  .  External documentation is not my strong suit when it comes to apps I've created, but internal comments have been such that I could come back a decade later and know what - and sometimes the why of it - I'd done.  Thought it was standard practice  ?  Now I don't feel so bad about some of the Web stuff I've done recently ... seems I'm in popular/common, if not good, company  .

On a slightly different, hopefully related, note ... how much does it matter between having in-line documentation as opposed to external?  Yeah, the obvious bit about not having the separate document, but what else?  The relevance is that I'm showing someone else how to do some rather esoteric Web pages, and we have a constant battle over in-page comments ... she claims they slow loading time.  For that matter, what weight do comments in compiled code have, as opposed to pure code?  Is there really a significant trade-off  ?  Or is the reason just laziness?

-barney (April 12, 2011, 10:59 PM)

Note: my opinion is of course influenced by my experience, which is mostly on fairly large scale internet/web technology solutions, on code that needs to evolved over months and years and with teams that will also evolve, and of inheriting such systems already a few years old and in trouble...

In line versus separate: you want both, of course, because when you are reporting about a system or picking something new up, you want to be able to do that by reviewing 1 file instead of having to scan the whole code. But when you are digging to reengineer or tracing a problem, nothing beats in context documentation to speed up the process. And ideally you want both without having to duplicate effort. I have always liked systems that can take inline comments + (ideally) syntax analysis and generate documentation - but then I was totally influenced by perl and its pod, then later javadoc/phpdoc so I am totally biased.

But still, I think there is some progress that could be made to minimize work duplication and maximise documentation value - from spec/user stories + code comments + code syntax => system docs, api docs, test cases etc.

In my opinion, if you dont have automation of these and dont have the time (and who has?) then:
- in line documentation comes first, because it is easy to maintain
- at least 1 arch document of the solution structure
- diary of design decisions and design debt (decisions we know could cause work or issues later if the system evolves in certain ways, but since we are not sure it will ever go this way and it saves time/effort/complexity...), easiest is to do that in the ticketing system or a wiki
- api, can be self documenting (eg in the case of WSDL)

Performance: In interpreted code the comments can in some cases have an impact, although it is something i received as received opinion, I haven't ever bothered to benchmark. I did notice an impact in javascript though, but that is because the files are sent to the client, so logically size matters.

If comments are an issue there is a way to get them stripped as part of the continuous integration/build/deployment process, several of the tools used in these set ups can strip comments prior to deployment, they can sometimes also do other forms of compressing