And I am tired of excuses to not document...
--hsm
"Never try to teach a pig to sing...it wastes your time and it annoys the pig."
| [reply] |
The excuse I hear over and over from programmers who don't write POD, don't write tests, and write incomprehensible code that they can include comments and everything will be OK.
Comments should be the item of last resort. For figuring out what code does, writing clear, concise code is first, followed by Pod, then unit tests and as a last resort, comments.
The reason for doing this in this order,
- Comments have no relation to how code runs. You can never be sure it is accurate and because they are never publicly (re)viewed, they can easily be ignored when doing updates.
- Unit tests do two things, test the validity of your code, and give a working example of how it is used. While it does not declare a context the code is supposed to be used, you should be able to write a proof of concept using tests.
- Pod is documentation that programmers will depend on to use your code. If your Pod is invalid, people will let you know or they stop using your code. It is harder to ignore Pod if you expect people to use code.
- Code should be first because it is the one thing that is ALWAYS done. Code is not simply a way of executing a particular action, it is instructions to tell the programmer HOW it is supposed to do it.
If your code is so abstract that people cannot understand it, you have created a Rube Goldberg Machine that cannot be updated easily and will eventually end up being disgarded by something that can.
The one thing I believe in is documentation, just not half-hearted attempts by calling them 'comments.'
| [reply] |
Excellent! An important distinction that regrettably those who neither comment nor document will understand. Typically in a maintainers mode I read the available material to at least get an idea of what was desired, expected, thought? Then I strip it all out to concentrate on what the code actually does. I have never bought into the flippant idea that code is self documenting as some of our fellow folk would insist, it is however the code and when working with it nothing else matters.
I hope you don't think D. Knuth is a fool for thinking that you are wrong in your order of process. He would insist that you design first and then both code and document at the same time. ;) In a better world with <oxymoron>intelligent managers</oxymoron> literate programming would be required— perhaps even build into the language!
--hsm
"Never try to teach a pig to sing...it wastes your time and it annoys the pig."
| [reply] |