Slashdot Mirror
The Importance of Commenting and Documenting Code?
mrtrumbe asks: "The company I work for is in the process of creating a development standard to be applied to all projects. The topics being considered range from dictating the formatting of the code (an issue on which there is widespread agreement), to creating a standard for commenting and documenting the code (a far more contentious issue). On the issue of commenting and documenting, there are two extreme views being considered with most employees' opinions falling somewhere between them." To comment, or not to comment. And if you do choose to comment, what's the best way to standardize it, company-wide?
"The first view is that commenting and documentation will protect the firm from bad programmers or a programmer abruptly leaving, make the code far easier to understand to someone unfamiliar with the codebase, and are necessary for all public, private and test code. The opposing view is that there are more effective ways to mitigate the risk of bad and disappearing programmers (like mandated shared ownership of code and sufficient oversight), that comments are not necessary for clarity and can be dangerous if not kept up to date (which is considered likely), and that documentation is necessary only for public code. Where does Slashdot stand on this issue? Please share any success stories and recommendations for a company-wide standard on commenting and documentation of code.
We just got rid of our out-of-date function headers and replaced them with doxygen-style comments. The function parameters, return values and called-by / calls information will now stay up to date, and the html reference output is handy.
Intron: the portion of DNA which expresses nothing useful.
Never comment your code. That way everyone needs to ask you for a fix when thinks break. Think of it as "employment insurance..."
For Gods sake man, you're just making so that you are easily replaced. Real men don't comment or document their code; instead we sit in high priced development contracts performing application support.
A brief decription of the object/class and then simple comments on any methods. That's a minimum but I would also go for single line comments for conceptually difficult peices of code that you know you will forget in a couple of weeks. Not overly rigorous but easy enough that people do follow it.
A good model for me would be the Java SDK docs and the javadocs tool but that's just me.
About the only thing a good standard will do is present options, advantages and disadvantages, and require that an explicit decision be made after appropriate discussion.
Stop it! Stop it! Stop it! The Noise. Make it stop!
No, seriously, you cannot comment your code and enforce that as policy. You can't impose standards and impose enforce that! It doesn't work.
You either know how to program/code, and commenting is part of that, or you don't. Either your staff knows same or doesn't.
Go ahead and establish "guidelines", you'll feel better. But I've been in this industry for over 20 years and applying "standards" for coding and "comments" has never worked.
Write un-obfuscated code, have peer reviews and walkthroughs, and have staff that know how to create... It's really all you need.
(As an anecdotal experience -- we had "standards" on a major project, and I accidentally created a Class without the proper capitalization. A peer came to me and confronted me on said transgression and wondered what I intended to do about it. I said I intended to let it slide and would try to be better in the future. He insisted we "fix" this problem and we spent (and I'm NOT making this up!) the next day's worth of time re-factoring the code (the IDE wasn't up to speed for this -- thanks Microsoft) to "correct" the "problem". Sigh)
If your code is not commented it's not complete. My advice is to fire every developer that doesn't think that comments are necessary.
If I haven't touched a project for 6 months it can take me a little while to get to grips with my own code if I haven't commented it properly - then again perhaps I just drink too much!
I don't think a standardized way of commenting is necessary though, as long as there is sufficient comments for a new team member (or a forgetful author like me) to understand the code in a reasonable time.
Haydn.
Time is an illusion. Lunchtime doubly so. - Douglas Adams
Just read this thread... http://developers.slashdot.org/article.pl?sid=05/1 1/30/1544256&tid=156&tid=8
Check out the best P2P sharing website: MEDIACHEST.COM
Comments won't protect you against bad programmers; they'll write bad/confusing code and comments no matter what.
However, I've found that writing semi-structured comments for each module and function (or object/method, if that's your poison) using something like doxygen is worthwhile for ongoing maintenance. It helps others see what the intent is, and provides a basis for writing unit tests. It even helps the original coder when they come back to the module 6 months later. It's not a matter of whether it's public code, just basic internal docs.
I use Pig Latin to comment my code. Job security, you know.
"Who are in control, they are not in control of anything - they don't even control themselves!" - Glen Beck
I think the hardest thing about forcing standards is that they get in the way of actually writing workable code.
If I have to sit there and worry if I have added enough comments so Joe Firstjob can understand what I am doing, the project is going to be late and chances are I'll lost that train of thought that I was following to get through that function.
My usual mode of 'documentation' use real language function returnUserShoppingCart and variable shopperLastPurchaseDate names and add comments noting loop/if-then statments and anything I know I will need a refresher on. I also use comments to state why I did something that way, ie: business rule in effect as of this date, etc.
Your best bet is to know your staff/fellow programmers, learn their styles (or at least become aware of them enough to follow along) and make sure you have checkpoint/target status deadlines. The last to make sure you don't have someone writing 'hola world' for 5 months.
I forgot what I wanted to say, but honestly, it was important.
But if "no comments" is an option, you must work on REALLY small projects.
I've gotten to the point where I comment en evmy throwaways, because I have a
dusty directory full of them and occasionally I pull one out again.
Here's the simple solution that works for me: any time I have to stop and think
about code, either to write it or when (re-) reading it, write those thoughts
down in the form of comments. I have *one line* of code that's particularly
subtle (it's a function approximation), so I broke it out into its own function
and gave it a page (printed page - 60 lines) of comment explaining what it does
and why the approximation is useful.
But I spent a day designing that approximation, so the think time was already spent.
All I had to do was write it down the first time.
Sometimes the comment gets a bit long and rambling if I make multiple
attempts at the solution, but deleting redundant text is pretty easy.
On the other hand, some functions are so obvious as to not need anything, although
I usually try for a one-line overall comment. I at least had to think about
how to break the work into functions and where a good boundary would be.
Seems like you missed a step. First you decide if you're going to use an auto-generated code documentation tool like Doxygen. That alone will dictate the majority of any comment-standard.
Commenting and documenting code is something all programmers should do. Not doing it is highly unprofessional and should not be allowed in any self-respecting firm. Making sure the documentation/comments are upto date is included in that statement.
On the other hand just because code is well documented that doesn't mean it's easily maintainable. There are various techniques used to generate good maintainable code. But without documentation any code more complex that 'hello world' tends to be a pain to maintain no matter what techniques you use.
I personaly also find the formating of code (and comments) just as important as commenting it. Reading code formated in a way you're not used to can be a pain and reading code formated in different ways doubly so. So a company-wide standard for formating code/comments would be a good idea.
There is one problem with comments, but it is a show stopper as far as I'm concerned.
Computers never read the comments, while programmers tend to read comments rather than code. The first part is obvious, and the second is easy to demonstrate. Together, they are a recipe for disaster.
Uncommented code has a number of disadvantages, but the overriding (IMHO) advantage is that both the computer and the programmer are dealing with the same thing, the code. On the other hand, with commented code they are dealing with two similar but distinct things, that are related in exactly the same way as a fine-print contract (the code) and the car salesman's verbal promises (the comments). When push comes to shove, the salesman's words mean nothing and the contract is what matters. So why even listen to the salesman?
-- MarkusQ
P.S. This is not to say that I never comment code; only that I do so sparingly and never trust the comments.
In the real world, you work on a project for a time then move on to something else. Then you or someone else is assigned to revisit your old code. You don't have time to relearn the code and you certainly don't have time to sit down the guy called in to fix it and tranfers your understanding of the project. (If you did, you would've documented the code properly in the first place, right?)
When companies don't comment and don't document their code properly, they begin this vicious cycle of rewriting old code because no one know how it should or does work and no one has the time to figure it out. Let me explain why.
Imagine you find a software package on the internet licensed in a way that suits your needs. Now imagine that software package, with very few modifications, will do exactly what you need it to do for you project. You have a choice: (1) Take that software, modify it, and deploy it, or (2) write your own from scratch.
There is only ONE determining factor in whether you inevitably choose (1) or (2), and that is DOCUMENTATION.
Now remember that software you find in your own company is no better or worse than software you find on the internet, only it has a much more liberal license for your purposes. But does that change the fact that in order to make use of it you have to understand it?
On my job, I have an approach to undocumented software. I start writing documentation for it, whether or not the author wants me to and whether or not there is really enough time for it. If I have questions, I find the author, and approach him with pen and paper. We sit down and write documentation together. Inevitably, by documenting what I find in other people's codes it ends up saving me more time than if I wrote the code myself, documented it, and debugged it. So I have been able to finish a great number of projects ahead of schedule because I don't write code: I READ it. (And this is a perl world too!) And in the end, others are able to come and read my documents and notes and reuse the software as well.
The radical sect of Islam would either see you dead or "reverted" to Islam.
Grow up.
If somebody asks you to code something (and you can get away with it) tell them this, "okay that is X hours for just the code and X*3 for the code and proper documentation."
Yes I made the *3 up. You know why? Because I have always had the misfortune on working on the kinds of projects where I either didn't get the time needed or the guy before me didn't do the documentation.
If you want to take a ride in your car you should walk around it making sure it is in proper working order like all the lights working. It is a law and enforced by people with guns. Now how many of you do it?
Okay, nobody. So now you are under time pressure, you are underpayed and overworked and you got a choice, either deliver on time or tell your boss your still writing documentation on the installer.
When I was still young and fresh I thought that following procedures is the way to do it. Boy was I wrong. The secret? Code fast and ugly and make sure you have moved on before the shit hits the fan. Oh and never ever be lumbered with a maintenance project. I never even seen documentation wich was up-to-date.
The entire discussion on wether or not to document is wrong. The discussion should be wether you will allot enough time to non-coding work. It applies to so many things, peer review of code, sharing and re-use of selfmade libraries, layout standards, knowledge sharing, etc etc.
The larger the company the more time can successfully be spend on non-coding things that however are always badly reviewed during your evalutation. Oh yeah very nice you tought everyone else how to code securely and made sure nobody else has bugs in their code. Now how many lines did you write? Oh, no pay rise for you.
So simply ask this of the people in favor of proper documentation. How will they find the time?
And ask the non documentation people if they will do the maintenance on their own projects 10 years in to the future.
My experience? I needly predict I need X to write code and then Y to write the proper documentation. I deliver the code and get the next project and if I protest that I am still working on the documentation then I am told that it can wait. I am still waiting. Oh and the risk of doing it properly? You get lumbered with writing maintenance and writing the documentation for everyone else because your good at it but a slow coder. ARGH!
Just comment the basics, point out in a readme.txt where to start reading and tell them wich bar in the neighbourhood serves hard liquor during lunch. Oh and if you comment some code out come back later and delete it. Can be very confusing if you have to wade through a problem where 2/3's is old code.
MMO Quests are like orgasms:
You may solo them, I prefer them in a group.
Windows is like decaf - it tastes like the real thing, but it won't get you through the day.
The answer (40 years of experience with this) is not to set a standard on how much commenting is needed; it's to have walk-throughs of the code with an intelligent reader who isn't directly involved with the code. If they can read and understand the code, it's enough.
Look into Fagan reviews for details on an effective way to handle this.
is have all the programmers program in the same style and guidelines. Examples include all SQL statements start with $sql_, making sure code is properly indented, variable naming that are easy to recognize, where certain functions should be placed in the directory structure, and the such. Simple things like that should eliminate the need to write a novel for every piece of software that you write.
May I be a sort of voice of reason, of a kind? comments are tasty things which should be used regularly and often. spelling and grammar may not be necesarry to be observed, but in my opinion, I would much rather see roughly one comment fFor every, say, 6 lines of code. I dont mean in exact ratios portioned out like rations .. you could have a whole page or two of comments sometimes which covers 3 pages of other stuff, if it's all somehow convenient. that's cool. And, you know, variables and routines with obvious names may not need everything documented .... but somewhere i should be able to get some information about much of what a system does. in my experience, it seems as though once about every sixth line or so, we do something a little subtle which a nice simple comment might help. more is good, yes. you know, and i'm talking like /* add interest, dump to screen */ or /* average RGB values */ or .. that sort of thing. simple verb noun descriptors which tell what's going on. The kinds of things your pseudocode should say -- you do remember seudocode, right? that's the stuff your CIS 101 prof told you you should always use, and you havent touched since?
I mean, I'm inclined to say "if you don't use commenets everywhere you should be shot!" but i dont have that many bullets, and i'm just as inclined to say "you cant make me use comments if i don't wanna!" but i also don't have that many bridges so i'd rather not burn them *all* down.
a nice sane happy medium is a good thing.
"Computers never read the comments, while programmers tend to read comments rather than code. The first part is obvious, and the second is easy to demonstrate. Together, they are a recipe for disaster."
So what do you think about executable models?
Document at the function level (javadoc style is nice). It's easy to remember and it helps you refactor. If you are documenting the internal magic, then the magic could probably be moved out into it's own function, which then gets it's own documentation. voila.
If you need a documentation/commenting consultant, I am available to guide your team through this process.
Technology Consulting & Free Downloads
Basically, treat comments like you should credit card debt. Use it rarely, only when you really have to, and try to get rid of it as soon as possible. If you can write the code in a clearer way, one that does not need comments, then do so, ASAP.
In a perfect world, the ONLY thing that you want to have comments are APIs into closed code (some outward-facing API that you aren't willing to give the source to). Everything else should only have comments when the code is too complex to be understood by reading it... and that code should be first in line for refactoring.
And never NEVER write comments like "the doFoo(Stringx, String y) does foo by taking string x and string y as parameters". This is useless, clutters up everything, and makes the important comments less visible.
"Your superior intellect is no match for our puny weapons!"
It SHOULD be hard to understand.
http://thc.org/root/phun/unmaintain.html
In all seriousness. I would just enforce "header" comments to a particular style (javadoc..etc). The rest is up to the individual programmer.
The trouble as pointed out earlier is that programmers/code reveiwer have to be always be updating comments as the code gets updated. This doesn't always happen and is the caused me personally some problems as I took the comment to be right, when clearly they were not. I use comments as a guide now.
I keep seeing all these arguments either against commenting or against verbose languages because, supposedly, they slow development.
Now, Maybe I've just been programming too long and have gotten too good at it, but typing is never ever a slow-point in coding; heck, even learning a new language doesn't slow you down too much!
The slow part is designing your code correctly so that it's fully factored and as bug-free as you can manage--this takes thought and a bit of time, but no where near as much time as it would take to do the same release with cut & paste (I've seen it many times).
So I'm trying to figure this out, why are people making these arguments? Is it that for unexperienced people it truly is harder to put comments in with your code? Maybe they don't know how they did their magic and don't want others to figure them out? Maybe they never took a typing class and it truly takes more time to code than think? I'm really at a loss here.
Oh, and as for the authors question, you have a FANTASTIC opportunity to improve your company tenfold. Take notes of those arguing against commenting. As soon as you've collected all the votes, throw them away and FIRE anyone who was against documentation--they should not be working in any company, at least not as a programmer! If you hired people who understood programming and the development cycle, that question would have never come up.
If you fix a minor bug, and a week later you realize it's created a major bug, but in the meantime eight dozen commits have been made by your team, it's not always easy to just roll back to the version before the one you helpfully noted in the CVS comment as being "the" bug fix; you really do need to tag bug fixes in the code itself. The more documentation, the better. Explaining the "fix" you made should be part of this, though it can be out of the code itself, in external docs -- as long as everyone knows that that's where to it, and it's not split among five different places. That's where standardization really would be helpful. Some people still only comment in CVS, and I think that's just not enough if it's a team project.
I agree, to a point. "Why" (and "how") comments are far better than "what" comments, but the fundumental problem still applies. Even "why" comments can obscure bugs:--MarkusQ
Never! Why do you think they call it code?
90% of being smart is knowing what you're dumb at.
If you fix a minor bug, and a week later you realize it's created a major bug, but in the meantime eight dozen commits have been made by your team, it's not always easy to just roll back to the version before the one you helpfully noted in the CVS comment as being "the" bug fix; you really do need to tag bug fixes in the code itself. The more documentation, the better. Explaining the "fix" you made should be part of this, though it can be out of the code itself, in external docs -- as long as everyone knows that that's where to it, and it's not split among five different places. That's where standardization really would be helpful. Some people still only comment in CVS, and I think that's just not enough if it's a team project.
# hah. I screwed that one up. What a perfect example of why commenting is important
Get off my launchpad!
I've been programing for most of my life and have only documented about 3 peices of my work where things got so complex, it was making my head hurt. Even then, my comment says "I feel sorry for the next person who has to figure this out..." or "Don't ask what I was thinking here...".
IMO, if someone comes up and asks for documentation, they need to be fired! They obviously either 1) don't know how to read code and shouldn't be programming; 2) Don't understand the problem the code is trying to solve.
Code is like a foreign language - you either know it or you don't. Comments are for people who don't know it; and if they don't know it, they need to find another job or learn the language.
When I program, I get in this "state" where I can't stop. When I get to that state, I am a VERY FAST programmer. If I were to document my coding, it would take me 5 times as long to write it because I would never get in that "state". On the rare occassion that I look at code and can't figure it out, I rewrite it because, obviously, the code sucks. To keep my code from sucking, I have very strict guidlines that I use when programming (in order of importance):
1. MOST IMPORTANT - use tabs in routines to show where routines start and stop
2. use tabs in routines to show where routines start and stop
3. If I do comment (yea right), Don't put parenthesis, squiglys, or brackets in the comments - it screws up vi's % command.
4. use tabs in routines to show where routines start and stop
5. Make variables' and functions' names intutive.
6. use tabs in routines to show where routines start and stop
and last, use tabs in routines to show where routines start and stop
If you use these rules and have a decent progrmamer, there's probably very little need for comments.
Keith
Support bacteria. They're the only culture some people have.
"The idea is neat, though such ideas often come with their own problems--specifically, version control and change management, when the models can't be easily treated as flat text."
.i.e. Smalltalk can have version control.
Well since for most tools the model is basically an XML file behind-the-scenes. Something like CVS is possible. Just as image-based languages
There are open-source tools that help one do MDA, like GME, StarUML, and Openmdx. The missing part to all of these is of course TDD (test-driven-development).
IMO, if someone comes up and asks for documentation, they need to be fired! They obviously either 1) don't know how to read code and shouldn't be programming; 2) Don't understand the problem the code is trying to solve.
On the rare occassion that I look at code and can't figure it out, I rewrite it because, obviously, the code sucks.
Hack Mplayer. Then come back to me.
May the Maths Be with you!
If you can't keep comments up to date in the code you're responsbile for, you're not competent to be responsbile for the code.
There shouldn't be any debate on the need for documentation. Document your code or hit the road. The only issue is where it goes, in separate docs or in comment blocks. (Doxygen and similar systems make it easy to generate separate docs from comment blocks. Recommended.)
Code reviews are the best enforcement - if you go in and everyone's asking "what the hell does this block do???", you need to comment it.
Tom Swiss | the infamous tms | my blog
You cannot wash away blood with blood
i work in a small shop where one of our programmers had a massive stroke the week before christmas.
as a non-"official" programmer, picking up the slack would have been a LOT easier if his code were commented.
Code, like a math proof, is written in a specialized language that people outside of the field are unlikely to understand well.
Try removing all text from a sufficiently complex math proof, leaving only the mathematical notation, and see if you can still figure out what the mathematician is doing.
Now try to publish a paper like that.
No matter how amazing your results, such a proof will not be accepted by the mathematical community. I've run across some very good papers that were discarded because no one, including the author, could understand what all that math was supposed to *do* anymore.
You should be writing code the same way as you'd write a good proof. You don't need to explain why 1+1=2, but you definitely do not want to skip over critical parts of a proof that are necessary to understand before reaching the conclusion.
I see your point regarding using source code control for change comments. The issue that I have run into putting change comments in the code itself is one that also happens over time and multiple changes.
Here is an example, let's say you change line 188 to fix defect 2287. Next week, another developer needs to change the same line to fix defect 3012. Does that developer append on to your comment or overwrite your comment? What if the developer completely changed line 188 so that your changes were lost?
I guess that there is no perfect answer so you end up putting change comments in both the code and in the CVS (or similar) system. The downside of that is the wasted resources and potential for error in duplicitous effort.
I wrote what I thought was a pretty decent article on comments a while back:
http://freshmeat.net/articles/view/238/
The gist of it is that the source tells you what the code does, and comments tell you what it's supposed to do, why it looks that way, how it connects to other parts of the program, any weird gotchas, and so forth.
Comments help you zero in on the part of the code you're looking for when you're trying to fix a bug; and they help confirm that the code really does what you think it does.
Use The Commentator - easy to use and very effective!
Who wants to read something like that?
(Babelfish used for translations)
The disadvantage is that you are stuck on that project forever! They can never move you to new code since you're indispensible. A boring life but secure if you want it.
I18N == Intergalacticization
Code is like a foreign language - you either know it or you don't. Comments are for people who don't know it; and if they don't know it, they need to find another job or learn the language.
To take your analogy of code being a foreign language on step further then, writing a program is somewhat akin to writing a tale. I would therefore liken writing code without comments to writing a story with no naration. Yes, it can work, but a narator works well to expose the underlying purpose of the tale.
Quite frankly it's people like yourself and apparently many other slashdotters who are wrong with the computer programming industry. Good coding standards can only take you so far without good comments and documentation to back it up.
My advice is to fire every manager who would fire developers over petty deviations from the norm.
Dissemination of information is important, and comments can be helpful for that. But there are many ways to skin a cat, and the ones that involve not skinning the cat but giving it a bowl of milk instead will earn you fewer scratches.
"Here is an example, let's say you change line 188 to fix defect 2287. Next week, another developer needs to change the same line to fix defect 3012. Does that developer append on to your comment or overwrite your comment? What if the developer completely changed line 188 so that your changes were lost?"
You append, because one of the purposes of a change control system is to establish a history of both the code, and the programmer. Plus , just because two programmers worked on the same line, doesn't mean that they worked on the same part of the line.
"I guess that there is no perfect answer so you end up putting change comments in both the code and in the CVS (or similar) system. The downside of that is the wasted resources and potential for error in duplicitous effort."
There's no difference. The CVS is the code, and the code is the CVS. The important things are "he who changes the code, makes the comments", and keeping the "comments" with the relevent code (a coupling problem).
An excellent analogy. Reading code is like reading an essay or a book -- if there isn't any help in finding the thesis of the essay, you're completely on your own to figure out what the heck is the point. It becomes so much mumbo-jumbo.
I've maintained code which was almost utterly uncommented. It makes it really difficult to do, because you need to examine each piece in minute detail to get an idea of what it's there for. And then spelunk all over the place to figure out when it gets used and for what purpose. The first thing you usually end up doing is annotating it with some rudimentary comments so you can get your bearings straight.
A long-standing habit has been to write the comment at the header of the function at the same time I'm declaring it. That allows me to get straight in my head what the heck I'm trying to do, as well as have a quick reference to it later when I'm perusing it.
My favourite comment mechanism is a javadoc/doxygen type thing where you can mark up your code, and then be able to peruse it's structure from a mechanism separate from the source. And you can easily do it within the structure of your code without much pain.
I think anybody maintaining that commenting code is a pointless excercise has no business writing code in the first place. The comments are the thread of higher-level thoughts that go into all of the highly specialized elements of actually writing code.
Lost at C:>. Found at C.
All projects, no matter how simple, require comments.
The comment (or documentation) defines the supported API for the method or function. It is effectively the informal contract between the person writing the code and the person calling it.
The importance of the design contract is that it allows you to refactor code effectively, rather than having to reproduce every single side effect and internal detail of the code in order to avoid unknown amounts of breakage elsewhere.
And I'm with the previous guy in the thread. If you don't understand why all functions need comments, you shouldn't be writing anything even remotely important.
And yes, even code you write for yourself should be commented, so that you can come back to it a year later and refactor.
For example, take a very simple piece of code: something in a math library to add two vectors together. Suppose you implement it, and your initial implementation is generic and happens to work with complex numbers, rationals, dates, even strings. Well, that's great, but then you profile and discover it's a major bottleneck in your 3D graphics application. You want to refactor it to a high speed piece of inline assembler. You only intended to use the code for vectors of floats--but if you have no design contract, people might be using the routine with all kinds of data types, because it happened to give the result they wanted—and your hopes of a quick and easy refactoring are dashed. You end up having to define a new fastfloatvectoradd(), replace calls all over your code, and maybe end up with the original add() as dead code as far as your application is concerned.
GCHQ Quantum Insert installed. If only our tongues were made of glass, how much more careful we would be when we speak
I beg to differ. If my library call is commented as "adds two integers", and you notice it also works for floats, use it, and then a new release has refactored code that crashes when floats are passed in... then when push comes to shove, I'm gonna tell you it's your hard luck. The comments are the contract; they're the specification of what I warrant the code to do. If it doesn't do what the comments say, then that's a bug, and it's my problem. If you act on the basis of what the code says, and something breaks as a result, it's your problem.
GCHQ Quantum Insert installed. If only our tongues were made of glass, how much more careful we would be when we speak
but before you draft any standards or anything crazy like that, try this:
take your programmers, pair them up, and ask them to write some code and explain with NO comments to the other programmer what is going on in the code. If they can get the person to understand the code on the first try, great! That explanation is what you use to comment your code. If you're talking about a routine, fine, just make sure the explanation is in the comments.
Then, take the same two programmers, switch roles, and repeat. You could even iterate over the process once or twice more and reassign the pairings. And heck, if it's an assigned task from management, like say, code a sorting algorithm, then that's even a bit easier.
The whole point is to get everyone onto the same page for what is necessary for comments without patronizing the other person.
> Good luck modifying code in a dynamically typed language that way. ... Just use a refactoring tool.
Bzzt. Thanks for playing.
The method I described works for all languages that have a statically defined execution that can be fully resolved at compile time. (This is the same subset of languages with which you can safely use a refactoring tool; lisp, perl, and python are not included.) Since there is no guarantee that your langugae supports such a tool, the "compile til it works" method is preferred.
The problem is not with dynamically typed languages per say, but with dynamic execution. Just as you could not use a refactoring tool to change x["foo"]() to x["bar"]() in C++, you cannot change a perl/python member function with a refactoring tool either (hint: internally both perl and python use tables for their 'objects')!
Things get even uglier when you include various dynamic function arguments (as opposed to say strongly typed parametric polymorphism) and runtime evaluation. These are things you cannot handle with either the "compile until it works" method or a refactoring tool.
In short: once you cross into dynamic lanugages, you can't lean on tools anymore. You've got to become a better programmer.
On the other hand, in the real world with real code, tools like BicycleRepairMan work great.
Of course, I could have code that evals a strong, or changes the base class of a live object, or alters the inheritance hierarchy, or whatever in my Python code. That's incredibly uncommon in good code, though, and it's up to me as a developer to know when I'm playing games like that and account for them.
In practice, for renaming a class/method/attribute, pulling up/pushing down methods and variables, etc BRM works find on 99% of my code--and the times that it doesn't are times that are obvious to anyone who knows anything about the system (it's not as though it silently fails in cases you'd reasonably expect it to work). And it integrates nicely with emacs and vim.
rage, rage against the dying of the light
How to comment your project and thoroughly preserve your sanity:
1. Ignore any standards anyone tries to force on you. Mostly such people are full of hot air, playing a role instead of just BEING a programmer. Things don't have to be buttoned-down. So, ignore the anal retentives and RELAX.
2. Start sneaking around. Gather up everything you can get your hands on, from original user specs to whatever else. Everything you can beg, borrow, or steal, put in a folder in your desk. When you have some free time, digest it and produce short, easy-to-understand summaries. And, summarize EVERYTHING: business rules, expectations, requirements, EVERYTHING. A short, clearly written summary is worth ten pounds of worthless suit-speak memos.
3. As you code, start each chunk of code (function, procedure, class, whatever) with a brief paragraph explaining, in your own words, what the purpose of the code is. Just briefly say "this is what I'm about to do, and this is why". Be brief, but specific. Mention anything weird, like odd parameters or whatever. If you have to return a weird string because Joe the Programmer is expecting it, explain it (without being cruel).
4. Within your code, use self-documenting variables and make sure your indentation, etc (style) is clear and easy to read. I know I bitched about "standards" but it doesn't hurt to read a short book like "the Elements of Java Style". It's a good book. Make your code clean and easy on the eyes. It only takes a minute. USE WHITESPACE!!! Don't clump everything together like a core dump, add some extra lines here and there. A carriage return is only a byte (two if you're on Windows). It ain't gonna kill you.
5. Whenever you do anything in your code that is non-obvious, like testing a column you got out of a database because there's junk data in there sometimes, EXPLAIN it. Just take a couple of lines to say "The import process sometimes sticks garbage in this variable, so we're doing a sanity check on it". You don't have to comment every single thing you do, but comment everything NON-OBVIOUS you do.
And, that's about it. I think it's as easy as that. There's no need for company-wide training, or workshops, or any of that stuff. Just a little common sense, and a little effort, and your code's clear to everyone.
My preference is to write self documenting code, but in the past even this has caused confusion for people trying to understand what it is that I've written. Good comments are worth their weight. However, Bad comments can cause more trouble than they are worth.
Personally, I think that the choice to comment should be with the individual developers, and any developers that choose to comment should be forced to take some kind of workshop so that they are commenting correctly. Imposing an "everyone must comment" ethos without training will waste time and make your code base even more unreadable.
I don't want to be "Mr No-sense of-humour", but writing deliberately hard to follow code is professionally unethical.
Training monkeys for world domination since 1439
Process standards are essential. Make sure you have them and that you have developer buy-in. Avoid contentious issues that have little factual support.
Off-topic: the first process standard you should introduce (if you don't have it) is source control; it has one of the highest cost/benefit ratios of good development practices. The second is configuration management (that is, proper control and version management of releases -- binaries and source code). The third is design and source code documentation.
Typographic formatting (where to put brackets, etc) is of questionable benefit, and it's not worth pissing developers off unless they all agree on it. There are several research papers that show a small benefit in having a consistent style, but the majority of this benefit comes from a consistent style within one file, and to a lesser extent within one code base. Typographic differences across code bases have little or no implication for development and maintenance. On the other hand, most developers read all styles with similar effeciency, and write their preferred style with somewhat greater effeciency (that other styles).
Typographic style also becomes a problem when you have legacy code that doesn't conform. What do you do when you maintain it? Update the style for the whole file; for the function being modified; just for the code you are modifying? Hint: changing the entire file or function makes it dramatically more difficult to use source control to identify (meaningful) changes. I have worked with several teams in which we have applied the rule "use the existing style for the file", with great success.
Commenting is both a technical issue and a management issue:
Technically, it is essential to comment code. Every reusable section of code (files, classes, namespaces, functions) should have a comment that explains what it is and how to use it. Without this, maintainers must make assumptions about what functions do, and how they are used; to confirm the assumptions they must read and understand the implementation. This is extremely inefficient.
Aside: some people think that the use of a function can be implied from its prototype; this is often incorrect. It is seldom possible to assume parameter boundaries, object state (in the case of methods) or error responses given only a prototype.
Every paragraph (block) of code that is not immediately obvious is a candicate for a brief comment indicating what the code is intended to do conceptually. These comments assist maintainers in navigating the code, and (in the case of bugs) understanding what it's meant to do instead of what is is doing (presumable erroneously).
A documentation standard should prescribe what must be documented, the "syntax" of the documentation (e.g. you could use Doxygen), and what the documentation is intended to achieve (e.g. for functions, a developer should be able to understand and use the function without having to refer to its implementation).
From a management perspective, risk related to poor coding can be mitigated by means of reviews and shared ownership; but risk also comes from the fact that intellectual property resides in people's heads not in source code. Unless you are intending doing a thorough walk-through of every legacy codebase with every new developer who joins the company, you need to have as much information as possible in the code, to allow knowledge to be transferred to new developers and maintainers. That means explaining the design and the implementation within the code.
As for comments not being kept up to date, that is something which is trivially addressed by source control and oversight. Every check-in can be reviewed by a peer to ensure the correctness of the code, and that any relevant comments have been made or updated.
Remember that source code is communication with other developers, not just instructions to a machine, and that makes writing style important. Sometimes it helps to think of source code like a book (the Book Paradigm).
i-name =twylite [http://public.xdi.org/=twylite], see idcommons.net
Everyone is railing on comments getting out-of-sync with code. This does happen. However, how many times has the average shop gone back to the design docs and altered them after finding out the initial design was unusable? I'll wager a lot less often then they've edited the comments in the code.
Comments are also the only docs you *can* alter without having to do additional work - checking out the document, getting approvals, etc. You've already got the code out, so you can change the comments.
I use braile. In ASCII.
Commenting Code
Effective and practical documentation captures the intended use of modules, classes and routines in a user-manual-like form. In order to produce highly maintainable documentation, practice indicates that comments should not focus on explaining how the code works, but rather on how the code is to be used.
If comments are used to explain how the code works, any alteration to the code will render the documentation obsolete, resulting in duplication of effort and inaccurate documentation.
Plain English at the top of the file and each code construct should be used to describe its unique purpose and objective. Inline, detailed comments should be avoided because they cannot express the mechanics of the code more accurately than the code itself.
By avoiding the description of "anything between the brackets", the formal documentation reaches the non-redundant level of abstraction needed to streamline the authorship, usage and maintenance of the code.
http://www.ptlogica.com/TwinText/paper.htmyou would have code patterns that would provide a framework for 95% of the code your company owns. I run a consulting company and here's what I did. I worked for a few years doing consulting work by myself before I had enough work to hire employees. I wanted to make my work simple and get to the point where I could do most of the coding in my sleep. I began looking at all of my code as just slight variations of the same patterns. I'd come up with a pattern, for say a persistence class, and perfect the format and consistency of it. Then for every persistence class I needed I'd copy one that matched the pattern and simply change the attribute/property names, database field & table names.
I've written so many apps with that technique now that I've got code patterns for about 95% of everything I need. And maintenance is so easy because all of the code for all of the apps looks and works the same even the apps themselves serve completely different purposes.
In addition I've taken all of the common facets of most custom apps and developed a common pluggable API with an underlying database that abstracts all of these details away. Things like role-based security, event logging, settings encryption/management, custom user directory and etc. So developers only tap into this API and never even need to write any code or re-invent the wheel every time user security is needed (for instance).
So there's not really much documentation needed because most of the code is very recognizable for any developer who is used to the format of the patterns. And since we perform code reviews on each-other's code it is always kept in conformance to the patterns. I can work on anybody's code even if I've never seen it before because I instantly recognize the patterns.
If you've got a whole team of developers who aren't used to producing pattern-based generic code it'll be hard to put a system like this into place. Especially since you have to develop the patterns over time as well as the common APIs you may need.
In summary the best documentation strategy is:
1) Consistent code patterns
2) Pluggable libaries of common code tools (Aspect Oriented Programming (AOP))
Martin Fowler once said: "At Object Mentor we call a comment in the source code a lie." He proceeded to explain that it was a lie because in a few months the comment and code will diverge, regardless of how much work was put in into trying to keep the two in synch.
I tend to agree with Mr. Fowler's sentiment on this subject, because there is no need for comments in the Test Driven Development (TDD) environment.
Ninty percent of my work when working on old programs is TRYING TO FIGGUR OUT THE DATA STRUCTURES. Not the code. The Data.
How about the 25 different letters used in the field cryptically named "F-STATUS"? OR a date in a field named "D-Date"?
Document your DATA structures you code-monkeys!
Think of it as a potential invoice
What are you listening to? (http://megamanic.blogetery.com/)
No you don't, I've had to (far too regularly) go through 5 year old code riddled with tagged bugfixes of various epochs and I can tell you that generally they are more harm than good. Trust me a four year old end of line comment that reads "SRQ 5678" is not helpful to anyone.
What you need to do is have a VCS with a good difference feature built in or read out version 1.23 pre bugfix & version 1.24 post bugfix & do a compare. THAT tells you what was changed to fix the bug better than 25 scattered tags (which may or may not be complete). Then, knowing what was changed you get 1.32 (the latest version) and undo the 1.23 -> 1.24 changes. I have used the VCS to backtrack through 50 revisions to find out who was responsible for certain braindead bugs & what I need to do to unravel them.
Remember, VCS means never having to put bullshit comments like that into your code.
What are you listening to? (http://megamanic.blogetery.com/)
By the way, I have seen some neat systems which offer integration of issue database and revision control; they're very neat and if you've got access to such a thing, use it! (I'd offer a link, but I can't quite remember the name of it...)
"Little does he know, but there is no 'I' in 'Idiot'!"
Code with comments on every line (short of certain function in assembly) is unacceptable.
There is something to be said for consistency. I like the idea of "self-documenting" code or code that is so easy to read that it doesn't need documents but the fact is that no code is that to everyone, you have to assume a lesser engineer will at some point need to understand what you're doing. Just get used to that idea. I've seen commentless code with sentance like variable names and function names getNewHisteresisValueFromNetworkThrottleGovner(..
While I generally think the idea of mandatory doxygen or javadoc comments is kind of overkill and if the code is done well then it's usually fairly obvious what the code does and worse, when you do some serious refactoring all that documentation is just extra luggage to move around I think that there is another effect that requiring them can produce. It shows when someone cares or doesn't care and knowing that might be more useful than documentation.
At one job I had, in an extremely high performance software engineering shop (world class,) they had a ton of rigid coding standards and guidelines. At the time it really seemed like a lot of extra hoops to jump through and I was younger and wanted it "my way" after a while though I had some converstaions with some people about it and they all thought that what was more important that consistent code was that if an engineer didn't care enough to follow those rules then they knew he wasn't going to work out. Mandatory code reviews, not becaues the code always needs it but it transfers knowledge, and then you oculd see them end in like 5 minutes because it wasn't formatted correctly or something wasn't documented, you go back and fix it and reschedule the review; if it takes too many reschedules then there is going to be a problem. And I kind of agree with that. You don't really have discipline unless you demonstrate it but the demonstration usually isn't really needed but it's a circular thing; you don't have the discipline to document every variable and function unless you do it but that probably doesn't really need to be done.
At other jobs, I've seen people want to use javadoc and doxygen only to find it's nearly useless because 15% of the code is documented correctly. If you've ever dived in to a large project, poking around in doxygen is nice if it exists, while it may not be perfect it can get you a nice lay of the land. I think if you have any desire what-so-ever to use a tool like that then I think it is completely reasonable to require all classes, methods, etc. to have at least minimal documentation. Even getters and setters can be documented and it doesn't really hurt anything (turn on folding in your editor if it's too much for you) and if you have people that refuse or cannot get themselves to do that much then you know some other problems your project is going to have.
why people take the in a lot of cases badly maintainable C/C++ (of course, it is up to the programmers to write proper code, but to what I've seen now) or VM-dependent implementations (.NET, mono etc) if they want to develop new (somewhere about 30% of the code you'll develop) crossplattform projects and either whine about bad maintainability or bad performance [both is subjective and relative, but the fact is that there are lots of whiners].
FreePascal provides a really great middle between both - generates fast code, you aren't penetrated by aggressive memory management (while it is still required), provides a very powerful lib, provides a very powerful toolkit (as an example - smart linking). Your code will be REALLY portable and RAD is given.
I wouldn't develop a client application in C++ (or ASM or whatever) today and I wouldn't take Java for system programming. FPC provides facilities for nearly every aspect of development.
Well, what am I actually talking about? People don't even want to hear that their world is uncomfortable as they are just holding too much at the old world...
ReadySET (open source)
"What problem does this project address?
Software development projects require a lot of "paperwork" in the form of requirements documents, design documents, test plans, schedules, checklists, release notes, etc. It seems that everyone creates the documents from a blank page, from the documents used on their last project, or from one of a handful of high-priced proprietary software engineering template libraries. For those of us who start from a blank page, it can be a lot of work and it is easy to forget important parts. That is not a very reliable basis for professional engineering projects."
Tough to roll back to a specifiec version? Whatever do you mean? Examine the output from "cvs --help diff" and then tell me that it's hard to see what someone changed between two arbitrary revisions/dates. Sure, it's not trivial, but that shows you *exactly* what changed and when it changed. A comment says "whoops" but doesn't detail why the line above was accidentally deleted and re-added elsewhere...
This, BTW, is why I like svn - every commit is repository-wide, not just per-file.
I prefer (in an ideal world) the check in comment to be the issue reference + a broad brush description of what was done.
PVCS/Tracker allegedly offers such integration but we've not got it working (not that I personally administer PVCS here) I'd prefer it if we went FOSS for issue tracking & VCS & wrote our own glue if it doesn't exist - it shouldn't be a big job & it's a nice bit of code to donate back that doesn't jeopardise any trade secrets...
The version of PVCS we're stuck with here sucks nuts & I'm pretty sure that a FOSS alternative (in addition to saving a fortune in ongoing support that we don't use) would be at least as good and easier to fix up to meet requirements.
What are you listening to? (http://megamanic.blogetery.com/)
If I find any bugs/issue numbers in code I have to work with the first thing I do is delete them. This sort of thing drives me nuts and makes me want to poke out peoples eyes with a sharp stick while chanting "Use CVS diff, Use CVS diff".
"IMO, if someone comes up and asks for documentation, they need to be fired!"
Okay, so how do you deal with external libraries for which you don't have the code?
How do you deal with large projects with hundreds of designers, where you have to go in and change someone else's code? (Why do you think there are whole *books* documenting the linux kernel?)
How do you ensure that when you come back to your code 5 years later (it happens in real life) you can figure out what's going on? If it took 2 months to get working in the first place, do you really think you can just start working on it again without introducing new bugs?
Documentation should primarily describe *why* and *how* something is being done, at a suitable level of abstraction. Inline comments should at least describe *why* something is being done. If the code is particularly gnarly (cubic splines, discrete fourier transforms, funky optimizations, etc), then they should describe *how*.
If you find that writing comments slows you down, then go back and add them at the end. But do it while you're fresh. There are times when I forgot, and had to sit for a while trying to figure out what the heck I was doing when I wrote it.
that I consider the ability to hide all comments so that code is more easily read and the non-functional and often misleading comments cannot result in confusion and lost time to be critical. Far more critical aspects of code maintainability include code being formatted in the style that the viewer has become accustomed to and usage of object names that are informative and not misleading.
One great advantage of removing comments is that auto code formatting to the style that you are use to seeing becomes nearly 100% effective. Handling of comments is always the big hangup in creating a good autoformatter. So, removing comments can have a very positive effect in this area. The need for formatting standards goes away if autoformatting to each engineer's preferences is 100% effective. This also helps in the portability of engineers as the spinup time into a different formatting standard when moving from one group to another goes away. Studies have shown that using the format that one's mind is trained to both increases code production and decreases bugs.
I've also seen very few studies that look at the statistical question of whether the cost of commenting pays off. There are at least two major cases in which the cost of commenting will not pay off, the code doesn't need maintenance and major changes in design, platform, or development technology force a rewrite. I believe these two cases are very common. For example, when features are added to code, they are frequently added as new modules that hook into only a few places in the existing code or completely replace existing modules. In either case, the cost of commenting all code on the chance that it may need to be understood by someone with a coding personality type that requires comments may not have been a good investment.
And that is another important point. Our current software engineering theory seems to look at programmers as all the same with all the same abilities and flaws. This causes as much trouble in our field as it does in the medical field. We need to be creating development platform technologies that allow each software engineer to be as effective as possible taking into account their specific strengths and weaknesses. This monocultural theory of software engineering we have today forces us to realizing the potential of the average of even the LCD instead of the realizing the maximum potential of each individual through techniques like automatically converting the view of the code base to each individual's needs. We are people, not machines.
My Company got bought by a shop with more money but less product then us. Three years went by and they were unable to assimilate us or even produce one their much anticipated new line of .NET based products. I found out why when one of their young programmers came to our location and spoke proudly of his steady improvement as a programmer, "I am up to 20% comments in my source code, when I first started I was really bad at about 5%" Good thing there were people here to hold me back, I really wanted to smack some sense into him.
Here it is real simple: machine code is for machines, programming languages are for programmers, comments are for managers. The product of a programmers work is code that compiles and runs. Time spend producing comments and documentation is not time spend producing product. There is only one place to look and see what a program does and it is not the comments. If your programmers can't read the programming language, the comments will not help.
For code readablity, a better metric than comment percentage would be symbol length. If you see a program with function and variable names that average 4 characters and another with a 15 character average you know which will be easier to read.
It took a real world war to end the airplane's patent wars. - Fâché Rouge -