Other Software > Developer's Corner

Documenting the Why not just the What

<< < (2/2)

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)
--- End quote ---

Hm-m-m ... thought it was just me  :huh:.  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  ;D.  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  :o?  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  ;D.

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)
--- End quote ---

Hm-m-m ... thought it was just me  :huh:.  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  ;D.  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  :o?  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  ;D.

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)
--- End quote ---

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

Navigation

[0] Message Index

[*] Previous page