Slashdot Mirror
How To Get Developers To Document Code
snydeq writes "Poorly documented code? Chances are the problem lies not in your programmers, but in your process, writes Fatal Exception's Neil McAllister. 'Unfortunately, too few developers seem to do a good job of documenting their code. Encouraging them to start can be a difficult challenge — but not an impossible one,' McAllister writes, adding that to establish a culture of documentation managers should favor the carrot before the stick. 'Like most people, programmers respond better to incentives than to mandates. Simple praise can go a long way, but managers may find other ways to reward developers. Are your developers occasionally on-call for weekend support duties or late-night update deployments? Consider giving them a break if they volunteer to pick up some extra documentation burden. Of course, financial incentives work, too.'"
It's called doing your job.
When the foot seeks the place of the head, the line is crossed. Know your place. Keep your place. Be a shoe.
But money costs money!
Finally had enough. Come see us over at https://soylentnews.org/
Nothing else seems to work...
In space no-one can hear your vuvuzela.
In this case, mandate works best because this is something that the developer SHOULD be doing anyways. Not documenting your code is inexcusable.
I prefer the theory that well developed code is it's own documentation. (believe this comes from reading a lot from Uncle Bob)
Crud loads of javadoc/msdn like documents aren't as effective as readable code and a few real world examples.
Once the boss learns about financial advantages of outsourcing.
Management says "do X" as fast as you can. Programmer does X and report back. Documentation, like proper testing or elegant design, takes time and thus cost money. It often saves cost over the long term but if the management doesn't care why should the programmer ?
If what you need documenting is at the level of comments within a file your problem is not that your programmers aren't writing comments it's that they are not sriting good software. If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.
I'll make an exception for comments to explain why a given piece of code is not actually batshit insane but required to work with a third-party library you have to use.
Producing documentation that spans classes and discusses how things are designed to work at run-time is, however, part of the job.
I guess today is a passable day to die.
I took a class at University many moons ago in software documentation. I got an 'A', and it was a valuable class in that I learned I sucked at it. (But I was better than most of the students)
The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.
As long as you hire great programmers you are going to get great programs. If you want great documentation, you need a great documentor.
All ideas^H^H^H^H^Hprocesses in this post are Patent Pending. (as well as the process of patenting all postings)
Or simply don't accept code that isn't up to snuff. That includes documentation and testing. Peer review will help make this happen automatically. Here's how it goes:
"I can't tell what this code is supposed to do."
"It toggles the widget's status."
"Is that documented somewhere?"
"No."
"Let's get that done."
You don't have to have this happen too many times before you just do it to avoid that. Same as all the other good code practices.
If you aren't doing peer review, you aren't getting the best code you could. It seems painful at first, but good developers actually like getting feedback on their code, and improving it. It isn't long before any good developer comes to desire it, instead of dread it.
"If you make people think they're thinking, they'll love you; But if you really make them think, they'll hate you." - DM
From the incentives and the carrot to the stick. Yet - as soon as I had my back turned, were I a team leader or a consultant or whatever, they went on developing - without documenting. It seems a near-impossible task.
Religous speak to God. Insane are spoken to by God. When all shut up, one can finally hear Shostakovich in peace
As I used to say "it was damn difficult to write, it should be bloody difficult to understand".
My UID is prime!
I'm growing increasingly convinced that in many situations, code only requires a minimal amount of documentation.
Code under development changes rapidly, so most of that documentation would never get used. And lots of code is best explained by the code itself plus small, local comments, rather than by separate, copious documentation. And then there's the fact that software often gets discarded before anyone would need to make the kinds of modifications that required extensive documentation.
It seems like sometimes, people who call for extensive documentation do so from the intuition that it's a diligent, long-term-smart strategy. I think the picture is muddier than that.
If you warn a developer up front that documentation of code is part of the job and you let them know there will be random code reviews they can't complain when they see no merit pay increases or eventually are laid off for now performing as expected. If a company does not allow for adequate time to have developers document code during a project it's the companies own fault, period.
Developers have been told time and time again through-out the last 20-30 years that documenting your code is good coding practice, but a vast majority don't. There are several reasons, and the one I hate worst of all is the "job security" response. Be honest, you don't want to so you don't.
Life takes interesting turns, but the most interest is when you're off the beaten path.
I've never had a problem of incentive or motivation to document my code; my problem is and always has been time.
Documenting anything other than conceptual stuff from the beginning is a bit of a waste (though far from a complete one) because the final product (due to bug fixes/spec changes/etc) never matches what you set out to do.
So when you do get to the point of post-testing where the code has stabilized and it's time to really sit down and document everything fully you're being given new stuff to work on. Sure I can (and do) raise a bit of a fuss about it and explain that if it doesn't get documented *now* it'll never get documented *well*. That always seems to fall on deaf ears though.
I think a lot of it is that the deserved biting in the ass never comes. Shortened product life cycles and customers that have become (wrongly) more tolerant of buggy software in production environments means that you can stumble through with a vague knowledge of the product and never really get fucked. It's the same basic reason that so many bad programmers have jobs.
A break from weekend or late-night on-call duties if they volunteer? Sounds like an great way to demoralize the (fewer) remaining workers who must share the (unchanged) burden.
// WHY
int WHAT(...) {
return HOW();
}
-Ouija- poke 53280,11:poke 53281,12
I write comments when what I'm doing is "clever", or hardware-required. Otherwise, I use meaningful labels and a readable syntax (C, for example, is K&R, except that all block-opening braces are on the next line for easy "line-up", any code beyond the current line has braces; variables have meaningful, not formulaic, names).
Too many managers and "religious" programmers want forty lines of comments for a twelve-line function. They ain't getting it from me, and, so far, my peers are happy with what I do. I comment shell scripts, PHP, Perl (more than the others), ... when there's a real reason, not just to fill out some silly "comments requirement". I put useful comments in svn checkins, too. Those are probably more meaningful than most of the code comments I have seen.
During my whole career I have been at least extensively inline-documenting the code I produced and got nothing absolutely nothing in return, if not trouble for not meeting a deadline that was poorly planned ahead of production anyway. Sure, extending deadlines somewhat is part of the business, but having a boss breathing down your neck despite knowing you wont be able to meet a deadline does not help, but I digress. My point is that if you do your job properly, which includes developer-readable inline documentation as well client facing docs, you should get something in return for devalorizing yourself as "IP asset". Be it extra cash, time off or at very least a pat on the back.
But we also know that nobody here or their managers are going to accept it and follow through, so why bother having the discussion?
You want it When?
On another note, coders that define the coding intent/objective first, in terms of coding (not client view) will have a skeleton of documentation to work from and their code may even be cleaner.
What is coding anyway, but the automation of images of human thought processes to be run on a a stone of minerals. So its really just a task of translation from human language to something a computer can process accordingly.
You want us to document our code? then GIVE US TIME TO DO SO.
Documentation takes time, I cant do it magically.
Do not look at laser with remaining good eye.
Nice. Right after Hostess files for bankruptcy TFA cites "hacker machismo" with a link to a list of "real programmer" attributes which includes 'surviving on Twinkies'. Seems like there's not much demand for that "food" after all.
Lack of documentation of code is a management problem. Management tends to have unrealistic timelines for development, without enough slack time built in. Documenting code takes a back seat when deadlines are looming. If adequately documenting code takes 10%-20% of the time to actually code, then timelines need to be extended accordingly. That is usually unacceptable in today's environment where corporate management takes the approach of get it out the door now, we'll fix it later.
I've found two camps at my company. Both camps document their code with comments and meaningful commentary. It is more a matter of the "design document" that describes the product or project that is a problem. The document that is perhaps supposed to guide the overall architecture of the product, and thus, the architecture of the classes, methods, interfaces, etc., aka. "the code".
:)
The first camp of developers just wants to get in and start coding. They often say "I need to code to figure it out." The actual web site works well, but new developers have a tough time maintaining that same site. The original developers are pretty much the only ones that can change the critical aspects of the site, and even then, as time goes by, that becomes difficult. But, they got the site up and live in the time allotted. And they wrote a 2 page "design document" when they were done - the doc was useless.
The second camp of developers writes a 50 page design, then starts coding. The actual web site works well, but the overall time to get the site up and live took 5 times longer (that includes the time to document.) The documentation evolved with the changes that were made along the way. Maintaining this same site went well at first, since the documentation was great. But, the docs slowly get neglected, and in a couple years, this site is difficult to maintain.
In the end, perhaps there is a happy medium. A "good enough" design document, and get started coding relatively soon. I used to lean toward the second camp, but now I lean toward the first camp
Documentation is a waste of time. You're better off writing your code cleanly so that somebody else can decipher it easily.
Most managers don't understand that they need proper code documentation (much less what "proper documentation" actually is), architectural documents, design documents, et cetera. They only realize it when it is too late and they need it. Then they blame the programmers.
Now, I don't expect much out of a "programmer" personally. A "software engineer", however, I DO expect better from.
A software engineer shouldn't have to be told how to do their job properly.
Loading...
"What!?! Comment my code? You question my honor! I'll kill you where you stand!"
-- Mukluk, Klingon Programmer
TLR
A man no more knows his destiny than a tea leaf knows the history of the East India Company
No comments. No paycheck. It is pretty simple.
I'm in odd developer in that I love documenting. I'm known for my extensive user guides, wikis...
However, I've never spent much time documenting code itself. Most code should be readable on its own. Good variable names, well named functions, well separated classes...
About the only useful in code documentation is if for a API that you plan to have proper javadoc or something.
But again, far more important than in code comments is documenting the big picture of how the application works. I'm big on diagrams and block diagrams... and I'm not going to do that in ascii :P So they normally end up on a wiki.
Finally there's the issue of time. There's a lot of things we *should* do, but we don't have the staff or the time.
Documenting code itself is pretty far down that list of things I would prioritize.
What happened to peer code reviews? Maybe it;s not 'quick' or 'agile', or 'extremee', but a code review is where you tell the programmer "You need better comments in here. etc. etc"
Send your programmers this link:
http://www.literateprogramming.com/
and have them read this book:
http://www.amazon.com/Literate-Programming-Center-Language-Information/dp/0937073806/ref=sr_1_1?ie=UTF8&qid=1326462347&sr=8-1
``Propaganda'' here:
http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html
I re-wrote the typesetting back-end of an interactive, graphical ad design / generation program as a literate program and it made a _huge_ difference in the maintainability of the system and made adding additional features _much_ easier.
Sphinx of black quartz, judge my vow.
Tell them that they will open source the code with their name pegged to it. Better yet, tell them you will send it to their college professors and any company that calls asking for employment verification...
I write a very small codebase, but it is used in webpages, so I know that others will see it. The embarrassment of ugly and badly commented code alone makes me keep my documentation up to date.
// Close the stream
stream.Close();
Documentation doesn't really have all that much value unless you can trust it, and in a large organization with a large code base there's likely to be code where the documentation is incomplete, inaccurate or plain old outdated and wrong. Once you cease trusting the comments and realize you must read the code to actually be sure what it does it turns into an evil circle. Nobody bothers to look at the documentation because it's useless and because it's useless nobody bothers to fix the documentation. And you fixing a few snippets here and there isn't going to change that perception and break that circle.
Like with structured code it's a lot easier to trash a code base than it is to keep it clean. You can apply a quick fix to the code and it works, but as you get layers or layers of hacks and quick fixes it grinds to a halt. For a time nobody's going to realize the documentation is deteriorating either, it's only as people lose more and more grip on what's going on - usually after key people left - that you're now spending more and more time locating the problem. And since there's no clear system to things, you keep adding more hacks.
Lack of documentation is just another form of technical debt, and like the entire economy we like to push that debt ahead of us. Maybe next week you'll get another job or get downsized or get outsourced or management will decide to replace it with a different tool or you'll be promoted or reorganized so it's no longer your problem. Meeting deadlines or performance goals now is more important than maintenance later. And your manager, well he's probably got no longer perspective than you, make the executives happy, collect a good paycheck, get a good reference.
Actually it seems a miracle that we produce software that keeps working, because it doesn't seem like much of anyone is in it for the long term. Workers care about their performance and keeping their jobs this quarter, CEOs and stock holders care about the stock price this quarter and that goes for most people in between. Documentation is cost and nobody wants to take the cost in this quarter if they can take it in next quarter. I've seen companies work extremely hard to get income booked in the current quarter or FY, not because of the two days but because of bonuses and such.
Live today, because you never know what tomorrow brings
Make time in the schedule to do the documentation.
When you're already working a 50-60 hour week just to get something out the door because some moron cut your estimate in half before promising a delivery date, where are you supposed to find the TIME to document instead of code, test, and ship?
Programmers may hate doing documentation, but it's MANAGEMENT's fault it doesn't get done. Period.
I do not fail; I succeed at finding out what does not work.
As someone who's started a new position and using classes with No comments, I can say I've wasted a good deal of time trying to figure out what certain public methods and certain classes do. They've used good naming conventions, but even so there is some subtly about what is done that could have used some explaining, plus looking through 1000s of lines of code before using a method isn't time effective. Its would be far easier for me to read through method header with inputs/outputs than to slog through code trying to figure out if this is the method I want. I don't want every line commented (I've seen that some placws), just the jist .
I came from an internal api writing group, and those using our code would just ask us questions if they couldn't figure stuff out, and we rsther they didn't so we documented ..
Examples or some test code I agree are super useful.
As an agile developer, I recommend against documenting your code.
You need to document the algorithms, but never the code.
Documenting your code will require you a lot of maintenance. Every time you change your code, you need to change your documentation. It's a never-ending process.
Instead, decide on a meaningful notation for your routines names (so any coder knows what the routine is supposed to do), and write tests, or more exactly functional tests.
Tests have a few goals:
1) check that your code behaves as expected.
Suppose that you have to fix a bug in your code, without tests, you cannot be sure that the fix will not be harmful.
It also allows greater flexibility in your code, and it will not smell like a rotting corpse.
2) show how to call your code, in order to get results. Examples are very useful for other developers.
3) confirm a behaviour. Your code does something, but sometimes, it's not clear. Your test should demonstrate the value of your code.
4) improve the stability of your program, and reduce the QA time.
Once the habit of writing tests is acquired, you'll start writing the tests before the code.
This is called TDD (Test Driven Development), and helps reduce a lot the amount of code you need to write, because you only write useful code.
Who wants to write unused tested code ?
I work for a firm that conducts a periodic release of code to its production environment. Those of us who regularly work the "release night" know what it means to document code well (and no, it's not just comments in the code). What our firm, and others like us, needs to do is rotate everyone through that situation, or others like it, so that they can see the flipside of their effort. Having to troubleshoot poorly documented code is a good way to instill in a developer good documentation habits.
Jesus told him, "I am the way, the truth, and the life. No one can come to the Father except through me. - John 14:6 NLT
If you want documentation and comments, to start with you should stop calling them programmers.
If you want documentation and comments, you call them software engineers and you allocate time for documentation, commenting, optimization, debugging, and other critical non-functionality tasks. Managers typically only allocate time to develop something that sort of works, not something that's polished, maintainable, debuggable, extensible.
I've run several engineering departments. Some have been good at documentation, others not so good. What's the difference? It's quite simple. Time When a company demands quick turnaround, its all the developer can do to get the code out the door. Good documentation falls by the wayside in these instances. In my experience its more about demands from the top than anything else.
You can read comments in source all day until you turn blue in the face, but you won't truly understand how something works or why it was put together the way it was unless there was some high level document describing major components and how and why they were assembled the way they were.
Recently I revisited code I had to put on the back burner from early last year. Of course my memory of the details had atrophied and didn't remember how it worked. But because I had written both in-line comments and high-level documentation describing how and why I did what I did, I was able to get up to speed in a minute. Granted someone else who looks at my stuff would take longer to understand it, but IMO it'd take them longer if they had just in-line comments.
Sanity.html - Error 404 not found
That specs often don't match up to real world. Bugs and logic errors exist.
So more often than not, a developer is doing several re-writes & refactoring of code to achieve a final working version. Documenting each variance would consume so much time that the developer would be fired for poor performance. To a developer, it is more important to retain job, (eat, have a place to sleep, etc) then to continually document during development.
The problem is in the "check-in". There should in fact be a policy of alloting time for documenting. Once a final or near final portion of code is checked in, shown to work and behave and play with other code, and shown that the specification was indeed correct on the desired functionality needs. THEN the code should be documented for future benefit.
In fact, if one is using a source code management tool. One can enforce documentation by requiring a second check-in version as File-Documented.
But time needs to be alloted at the end of a task to document. More often than not, a developer is working on a time constraint. Management wants the fix/update as soon as possible. Developer checks code in as soon as complete so as to resolve the real world issue, and is almost immediately handed a new task.
So yes, this is a management problem, not a developer problem.
I had to bail someone out -just yesterday- and the conditions were this example to the letter. The code wasn't "bad" but it wasn't perfect and certainly not something I'd like to admit to writing. It had precisely 0 comments. If documentation was a requirement I'm certain I would not have finished at all.
The best way to have programmers write quality code is to automatically enforce it. Have an automated tool verify the code for comments and run it on your build server each time new code is committed. I am a .NET developper, so each time I commit code, StyleCop and FxCop are run on the build server. This means my code is always commented, hell even spelling errors are not allowed!
If I am too lazy to comment, the build server sends an email to the whole team informing them of my laziness.
Exactly this. In a lot of instances the best case scenario is that the project timeline already tries to squeeze too much development into too little time, so even to hit the initial deadline for just producing the raw code you're still reliant on developers working over on their own time. To those who suggest incentivising with money, a better idea would be to use that money to take on another developer and spread the work so that the deadlines aren't always insanely tight (though in reality the second another developer is hired either the timeline will shorten or the workload will be increased).
Did you get the memo?
Ah! Yeah. It's just we're putting new coversheets on all the TPS reports before they go out now. So if you could go ahead and try to remember to do that from now on, that'd be great. All right!
It's not management. It's not lack of financial incentive. Mgmt doesn't have time/energy to scrutinize docs, and paying for docs is stupid because you'll get filler.
It's thought leaders on the team. You get some architect who wrote the system and fully understands it, PLUS he's smart, PLUS he's a git r done type (remember? remember? smart, gets things done? Thank you, Joel Spolsky). Result: the smart guy everybody looks to writes no docs. He doesn't need them. It doesn't occur to him that others might need docs, because it's not an immediate problem (fire, crisis) he can put out and be a hero. It's friction. No payoff for him to eliminate _that_.
So, everybody on the team follows his lead. There's no team culture of helping each other out by writing little love notes to each other that say such sweet things as "Returns the two highest priority items that are neither red nor flibbertygibbits (<see cref="isFlibbertyGibbit()"/>)."
Six months from now, long after I've moved on to something completely different, am I going to remember a function's return values? The inner workings of a particularly complex algorithm? Or the reasoning while a special case has to be handled differently?
If it's not going to be obvious to myself later on, it's worth adding a concise comment to explain.
Ita erat quando hic adveni.
First, what is the goal? The goal is not well documented code, what use to anyone is well documented code by itself. What you are looking for is a product that works and is easily maintained. Good code and any documentation is a huge part of easy to maintain. But where many people go wrong is that they see code documentation and commenting a critical part of a project. To the point where it starts to interfere with the creation of a good product that is easy to maintain.
So when looking at documentation it needs to make sense for the endgame. Who is going to use it? When are they going to use it? How much effort is going into its creation? I have seen projects where thousands of pages of documentation were generated where the only thing ever read again(other than by the document review team) were the few pages that documented the steps for configuring the server. When the next version was created nobody referred once to the old pile of documents that had every detail in the universe.
The next question is: what is documentation? This might seem odd but documentation can be the very directory structure itself. I wonder where the client code, maybe it is in the directory named client_code.
In agile or XP programing you don't tend to look too far into the future. So two critical documents that would be very active are your todo list for this cycle and a wishlist for future cycles that eventually turns into a todo list. The todo list, when done, can be chopped up into a crude set of documents that show the past if anyone were to be interested.
Lastly the code itself is an excellent place for documentation. A quick explanation of what it is about and why it exists can be useful if the file isn't already named verifycreditcardnumber.c.
So I don't think the criteria is so much poor or good documentation; so much as it is about useful documentation. If non programmers are intimately involved then lots of screen shots, text, and flowcharts are needed. If programmers are the only parties then it might almost all hide in the codebase with the exception of the screenshots mockups.
I always document my code. It saves time later. Six months down the road I'm not asking myself "why the hell did I do that?" It's for my own protection. I've had programmers tell me that they don't document their code because it's obvious what the code does, and sometimes that's true. But I think at least some of the resistance later to add features or fix bugs has to do with not wanting to struggle to remember what the code does. And -- this is just me, but -- you probably don't want to have a reputation for being uncooperative and not a team player in a down economy.
In a very early job, a guy with more credentials than I wrote a program we all used in a language I didn't know. There was a longstanding bug which he refused to fix [1], and he kept the source in a protected directory. So one night we broke into his account, I scooped the completely undocumented code, figured out the problem (had to change *one* (1) character!) and distributed the new binary. It took him awhile to figure out what happened. Boy was he pissed.
[1] Whether this was a dominance game or he really did not want to try to figure out the code he had written months earlier was a point lost in history.
Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
Good / Fast / Well Documented
I will document when I'm given the time to document.
If it's always the tyranny of the urgent, if there's always some fire to put out, I won't have the time to document.
I had a job where the manager was always complaining we didn't document. But he never fought upper management to give us time to document.
If you say "I have to have documentation and it is a deliverable" you will get it. If there is always something more important to do, it won't get done.
Except for ending slavery, the Nazis, communism, & securing American independence, war has never solved anything.
The agile people say you must never comment at all because you might change the code and then your comments will be wrong. This is only true if you're describing what the code is doing. If you are describing how the code supports the business, the comments will probably still be correct.
The scholarly types say you must comment profusely. Certainly comments help in areas where the code might be confusing for a newcomer, but no amount of describing what the code is doing in any given piece of code will shed much insight onto the business processes that code supports. Many programmers out there are just... bad... and they will probably not read the comments and screw up your code, anyway. Not that this is a reason not to comment your code. Having a comment with a warning might constitute useful proof of a given programmer's... badness... in the event that your code is screwed up in the future. If you comment, it is wise to make sure the evidence is something you wouldn't mind having come to light in the future.
Code itself is a specialized language by which two programmers can communicate, often across a gap of many years. An understanding of the business is both required and usually assumed by one programmer or another. If one of the two programmers has a less-than-perfect understanding of the business, his code will reflect his confusion. If the programmer reading the code has a less-than-perfect understanding of the business, he will find the code confusing no matter how good the comments are. If both programmers have a less-than-perfect understanding of the business... well... that's the situation we most often find ourselves in. And that's usually when people start complaining about documentation.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
Very hard. For some people. The code tells you what is being done. Sometimes that requires a line of explanation. The rest of the cognitive layer (i.e. the code documentation) tells you why something is being done a particular way, so you don't have to engage in another expensive research project.
The best exercise I ever had in documenting code was rewriting a colleague's code. All I did was take the comments, sentence by sentence and rewrite them using the least number of words that preserved the concept. Paragraph length sentences often reduced to as few as 10 words. That's not all, of course. Some comments were eliminated; others were rewritten in their entirety. All were arranged to emphasize the flow of concepts, rather than the specifics of the code. It's nontrivial.
Please do not read this sig. Thank you.
It really can be done. If your company has a culture where it is just how things are done, people will do it because it'll be more bother for them not to (as they'll get bothered when they don't).
I'm not saying it is trivial to do, just that it can be done. You have a corporate culture where that is how it is done, and people on all levels understand it, it'll be done. When the John Wayne programmer who refuses to do it comes in, he'll learn when every time he submits code it gets kicked back and the team lead comes and explains again that you have to follow certain conventions, document, and so on.
As an example of where it does happen would be Microsoft. If you talk to anyone who's seen the Windows source (either at one of the many universities that has a license to have it, or from the leak a few years back) they'll tell you it is very good in that regard. It follows consistent conventions, is well documented, and so on. That isn't coincidence, it is because they have a culture that demands that.
I expect it is also the sort of thing you seem more of the bigger and longer term the item is you are talking about. Something like an entire OS like Windows (where you are talking a ton of functionality, not just a kernel) is going to require a good setup since the code will be around for a long time and worked on by many people, and is exceedingly large and complex. When you are talking little "fix it" programs as many people have to do to make something work as a sysadmin, then it is less likely to happen.
One requirement should be that code documentation, clear enough for a junior programmer or someone from the accounting department to successfully follow from start to conclusion, shall be produced for each component along with the code.
Then, the project leader shall be responsible for seeing that code, and its documentation, is included in the check-off document for each system, subsystem. and function.
Publicly "score" your programmers for the elegance and completeness of each milestone task. If I was the project manager I would probably run each component through Rose or some other UML environment to be included in the documentation (after it is compared with the original/changed design).
Changes should also be documented. So should maintenance changes, but that is usually where I find the least comprehensive documentation. It is the leader/manager's responsibility to make sure the PROJECT is complete, not just workable. It is the developer's responsibility to make sure that his/her portion of the project is complete, not just workable. If the developer can't write a description of what he did that could be understood by a dumb-ass, then he probably doesn't know what he's doing anyway.
"The mind works quicker than you think!"
If the code can not be understood by reading, the consequences of even isolated out of date or mistaken comments are disastrous. Imagine a function that claims to authenticate users but doesn't. Instead, consider using higher level level languages and tools as well as separate utility methods - like heap sort - from business methods. Documentation if for design and protocols, not for what each line of C does.
What must be documented are the complex procedures and why it is doing it. Or if a previous simpler approach has been tried and then removed for a different non obvious procedure, that fact must be documented. Example:
"This class maintains a multi map of triangle pointers, sorted by area, to solid body faces. The sort key is a double, the truncation errors differ between Linux and Windows, so the order of visitation is not the same. When we used a simple std::multimap(Triangle *, FaceList, double),[*], the tables had different orders in different platforms. To provide repeatability we use a tolerance and tie breakers to make sure in both platforms the table will have the same order. It is called by render class, in a not very deeply nested loop. So CPU performance is NOT critical. Code is written for ease of maintenance and development, not optimized for CPU or memory." Such comments are useful, if maintained and kept up to date.
But most of the time it is not done. You see beautifully formatted comments created by macros in the editor, that occupies so much of screen real estate, I am not able to see both the code and the comment. Example:
[*] Syntax nazis: Slashdot formatter would not let me use angle brackets there. So I used () for illustration. /***Function Foo**/
it so stupid, I feel like screaming. If that coder is still working for me, I can scream at him or her. But mostly it is people who have left the company ages ago dumping that legacy POS on my lap.
sed -e 's/Chuck Norris/Rajnikant/g' joke > fact
... instead, they should program according to the documentations.
Here's what doesn't work: Anything, no matter what, if at the same time you put them under deadlines and other pressure to deliver results by (insert arbitrary, always too-short deadline set by you, your boss or anyone else but the coders themselves).
When the pressure is building, time is running out and the project is late, everyone in the process considers documentation to be the first thing that nobody would miss. So it's the first thing that gets dumped. And, of course, it's not as if the coders would be given time after the deadline to fix it, because there are no bug reports from clients regarding missing comments in code, obviously, and the next deadline for the next project is already approaching.
It's one of the many reasons programming as a craft is still in its diapers: Bad management.
Assorted stuff I do sometimes: Lemuria.org
I often hear that the proper approach is to document WHY you did something.
I am not a coding guru or even have formal studies on that field, I am really just a hobbyist, so anyone here has a few good valid examples of a "why"? I'd like to comment stuff properly.
So far I use non-shortened descriptive names for variables, functions and types, but I don't use that many comments. For example when parsing tokens in a string I write stuff like "//The format is ", but even so I feel the code is doing a better job at explaining it than I do.
As I went with the lengthy names, I have less problems getting lost on my own code, but I feel I am misbehaving. I blame my lack of formal education in coding, but would like to have some quality standards nevertheless.
The purpose of in-code documentation is to bring awareness to the various situations surrounding certain parts of a program. Contracts, parameters, and protocols already have a place in documentation of its own.
You simply need to realize that the human mind goes through a lot context changes when doing programming--it's not likely that anyone has the same mindset the next time they touch the same logic.
Documentation in this sense is to write as much or as little required to bring awareness to assumptions, consequences, etc--it's not like writing the philosophy of the API, defining its parameters and protocols. You may have already written that, as it's the reference for both your own code, and for the users of the API, and other programmers.
It's called being lazy and short sighted.
If you aren't documenting your code, you are bad at your job.
The Kruger Dunning explains most post on
I think the real problem is trying to measure code readability. Policies and coding standards try to address the issue while avoiding it by mandating frills that they think will kind or "imply" readability - function length, number of spaces in parentheses, badly defined Hungarian notation (dead, thankfully), Javadoc or similar commenting standards, and so on. But there's no getting around the fact that the only way to measure code readability is to read it.
This means that you need to put code review at the centre of the process. Not necessarily anything heavyweight, but just require that one other developer reads and understands the code (and points out any obvious flaws) before committing - with the limit that any questions the reviewer has should only be answered by changes in the code, because a question implies a readability problem. The developer can add comments, or rename variables, or restructure the code to make it clearer, but the end result should be readable code with fewer bugs (bugs live in hard-to-understand code, simply adding some intermediate variables to a complex formula can make them go away).
As long as the code review itself doesn't get bogged down with issues of How The World Should Indent and things like that - that's always a risk with developers looking at each others code.
A) had it been commented, it would have been easier
B) A comment should take a few second. If you are taking an hour for every 8 hours of code for commenting, then you are doing it wrong.
At least the next poor sap will ALSO have to take longer to change something because you didn't comment it either.
You people are just making excuse for being sloppy.
The Kruger Dunning explains most post on
Use COBOL. Those guys in 1950's sure knew their stuff. Self-documenting code. It forces you to write almost normal English.
If a function get so out of date that it original intent is no longer valid, you fail as a programmer.
"explain what a piece of non-trivial, non-intuitive piece of code does."
so you know what every other programmer in the world find intuitive?
You also assume you did it correctly. Something everyone else will need top assume if they don't know the point of the function up front.
I have seen this all too often. Where the code looks like its doing everything write, but it turns out is doesn't and it takes hours toy figure that out because the dip shit didn't bother to tell anyone the point of the procedure.
When ever I find this, I ALWAYS tell managers that I would have been done quicker if the original programmer had been professional enough to leave a 30 second comment.
Yes, unit test are critical. They shorten QA*, and make it easier to find gross bugs.
But you can write code that passes a unit test but is still flawed.
*really part of QA
The Kruger Dunning explains most post on
He likes to fire programmers!
I document my own code primarily because I have a crappy memory. Perhaps if you kick the problem programmers in the head enough, they too will have crappy memories and want to document their stuff.
Table-ized A.I.
Comments and documentation about the code is probably necessary, but where i work as a sysadmin/customer consultant. my main problem is that not even the runtime configuration options are documented by our cowboy developers (microsoft style, you know with an ini file without a single comment). Off course the devs whine everytime they have to do support because nobody but themselves have a chance in hell to understand whats going on, but them selves! i am contemplating putting a wall between their dev systems and ANY demo system. so that only a sys admin can install their code for demos ? (forcing them to make the application deployable by someone who havent acually written the f****** code.)
I'll even document somebody elses code,,, just kidding. Bazinga
"How to make sure developers maintain comments to reflect changes in code"
I always document my code. It's really not that hard to do, particularly if you do some of it while you are still coding. Back in the mid-90s I worked for a company that forbade it's developers from documenting code. You could actually get in trouble if you did it. Their thinking was tha it was a "waste of time" and didn't add anything of value. I strongly disagreed, of course, but they wouldn't budge. It was very frustrating.
but in a list of programming truisms, was:
"No documentation! If it was hard to write, it should be hard to read."
useful rule of thumb is that programmers should produce documentation that's "good enough" -- and no more. If it gets the job done, it's probably good enough. Any additions are just as likely to be redundant. If that sounds vague, that's because it is;
Thanks Mr. McAllister, that clears it up completely. Bribe, threaten, or otherwise coerce programmers to do ... something, but I don't know what that something is.
I worked on a very large project a few years ago where the company did a study to correlate the number of comments with the number of reported bugs in the code. It revealed exactly what I already knew: the more comments in the code, the more bugs were reported against it. There are several reasons for that (complexity of code, skill of programmer, etc). Fact was that while fixing all those bugs we found that the comments around the bad code were usually incorrect: the code didn't do what the documentation said it did. So out of necessity we adapted to the situation, first thing to do when fixing broken code was remove the comments (because you shouldn't trust them), then figure out what the code really did, fix it to do what it was supposed to do, and (possibly) add back a few succinct comments that were correct.
You want developers to document code? OK, a few simple steps:
Documentation might be improved if it were made more of a social activity instead of a chore. That is, if the process is made one of interaction with other people, providing feedback and direct contact. For example, an informal whiteboard discussion followed by a writeup and then formalization. Few people enjoy laborious banging away on a keyboard explaining, but probably people will find it a lot easier to give a general explanation followed then by the detailed structured written material. With social interaction, it can make it easier to see when what is clear to you is not clear to others, hence needing better coverage.
If it was hard to write, it should be hard to understand!
http://www.thinkgeek.com/homeoffice/stickers/9d48/
There are tools that will reverse engineer code to produce UML, or DB schema to produce ER diagrams. Add good naming conventions, IDE automatic code completion in IDEs combined with tools like JavaDoc go a long way. These need to be ubiquitous.
The same process improvement we've seen automating the build, unit testing and deployment needs to be applied to take the donkey work out of the documentation process.
Ask to see their comments before they start on their code.
I find that if I will write out what I want to do, prepend a comment character to the start of each line, and then start coding, that I stay focused and proceed much faster.
Aah, change is good. -- Rafiki
Yeah, but it ain't easy. -- Simba
A professional follows standards appropriate to the job in hand.
Coding is but one step in the process of creating software, and not more or less important than the others.
Any job needs a design stage, the output of which is documentation.
Some jobs need very detailed design stages, possibly including pseudo code.
Every job needs an implementation stage, this should include documentation as to why a particular method or structure is used.
Every job needs a testing stage. Even the smallest job should specify a minimal test data set. Mission (or life) critical systems should specify a test environment which covers the whole envelope of parameters / states which the software is expected to handle ( that is not the same as expected to meet).
Every job needs a sign-off stage. Self certification should only be used for very simple jobs, and even then should include a statement by the designer/programmer/tester(s) that the stages have been done, or why in this case they have been skipped or are continuing at the same time s release. Yes it does happen even in the best shops, but for Turin's sake write it down, and insist on it being done before further change to the affected software.
In a really good shop, with a proper development environment which includes source code locking and version management, stage completion certificates should form part of the build dependency tree.
If you are a manager of a shop which does not have such standards, then it is your professional duty to implement a scheme which allows you to certify that software that you release is fit for purpose. If you have staff who will not or cannot work to such standards, then I suggest that you ask them to sign a release form in which they accept personal responsibility for any failure. If they are willing to sign that, then you should be able to persuade them that proper design documentation is a good way to cover their asses.
If you are a "coder" in a shop without proper standards, then are you a professional? If you are you will set up your own scheme and stick to it.
Carrots, sticks, medals and back patting may have their place in life, but if you want to be in a profession, then standards are an inevitable component of the job. That's what profession means.
Encourage your staff and your peers to follow standards, and get involved with developing local procedures which help you to produce software fit for purpose (and that is not just fit for release). ,my lawn, I have to finish documenting a load of COBOL before I can get out of purgatory.
Now get off
nec sorte nec fato
...nor is it (or at least SHOULD it be) different than the code from a management standpoint. For example, when I do estimates, whether its for my own code or for those under me (which I try to avoid anyway- the people that will do the work should at least be involved in the estimates, but I digress) I always count on good, proper documentation being part of the process. It's part of the work to be delivered, plain and simple. Of course, I neglect to tell those above me that :) Fortunately, over the years I've built up a strong reputation and when I tell people it'll take a month to do something they know it'll take a month and the result will be good. Such a reputation certainly helps.
Some people treat documentation as optional. It's not. Not in the slightest. Documentation is as important as the actual code, and often times it is MORE SO. Why? Well, no matter how "self-documenting" the code is (which is an invented BS term anyway most of the time, but I digress) it still doesn't mean you know why the code exists, how it's used, how it's intended to be used, and WHAT THE ORIGINAL DEVELOPER WAS ACTUALLY THINKING WHEN HE WROTE IT. Knowing all those intentions can sometimes be the key information you need to debug something, especially when you didn't write it (or you wrote it more than about six months ago, which for all intents and purposes is the same as code you didn't write yourself).
Fortunately, writing good documentation is actually pretty easy. Simply put, you do it in two general steps:
Step 1: Write an outline of the code in comments that describes the overall structure, the general flow of the code, how you expect it to work and why its designed the way it is. Generally, write one comment block when you expect to have a method, and then each logical block of code within each method, in other words, the steps that you logically need to do to solve the problem at hand.
Step 2: Under each comment, fill in the blanks, so to speak, with the actual code. Of course, make it "self-documenting" code, for what that's worth (it's not a BAD thing at all, it's just not the ONLY thing that matters).
That'll usually do the trick. It also has the benefit of forcing you to (a) think through your design up-front and (b) stick to that plan throughout. Naturally you'll find places you need to make adjustments as you go... programming is more a creative process than an engineering process much of the time... but having that initial plan is still better than no plan most of the time. It'll also help keep you from introducing those pointless comments we've all seen (vis a vis: a=a+1; // Add 1 to a)
If you include the time it takes to do this in your work from the start it doesn't even add more time, and I'd argue in my experience actually SAVES time in the long-run because you catch some silly mistakes before you write any real code, when it's still easy to make changes.
If a pion (n-) collides with a proton in the woods & noone is there to hear it, does lamdba decay into the source pa
considering that you've claimed that i've claimed i was an expert, and that i ran from you, and now you're claiming jay did the exact same thing, perhaps you'll understand why i see no reason to believe you. probably, however, you won't, because you're an idiot. you admit to abusing women, and laughing about it. you're disgusting.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
what is worse, libeling someone that abuses women, or being someone that abuses women?
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
i am not a sockpuppet. i am michael kristopeit. you don't believe me, because you're a paranoid delusional admitted domestic abuser.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
and every couple i've ever known that "got along pretty well together" broke up... that's what people that get along with each other do. they break up... and then they contact people that have their picture with you on a website and request to be removed because you abused them. you're an ignorant hypocrite.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
you're an ignorant hypocrite.
i doubt you can stop.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
you're an ignorant hypocrite.
i have already said many times i own my own home. i own my own home. i did it again. my taxes are paid. you're an idiot. you're a liar. you're a moron.
i doubt you can stop.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
you're an ignorant hypocrite.
i doubt you can stop.
if you think you're abusing me, you're more pathetic than i thought.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
Translation:
Business decisions regarding a manufacturing/creative process involve trade-offs.
Well, duh....
Some degree of commenting is a necessary part of the job. Some degree of documentation might be better done by a different person from the one who did the code. Sometimes comments are good, sometimes bad. Sometimes the absence of comments is good, sometimes bad. This sort of thing is nowhere near as unique and exotic as software developers think it is.
Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.
Alexander Peter Kowalski seems to have many unsatisfied customers
Alexander Peter Kowalski
903 East Division Street
Syracuse, N.Y. 13208
Apartment #1, Lower Level
i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...
Jan Kowalski (Age 65+)
315-422-5417
E Division St
Syracuse, NY
Associated people:
Alexander P Kowalski
i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...
cower in my shadow some more, feeb.
you're completely pathetic.
The danger in your method is when (code below) gets changed, but the comment does not. As a result, the comment says something different than the code. That's where the advantage of "self-documenting" code comes in. When you change the code (to also self-documenting code), you don't run the risk of saying two different things.
The comment changes when the code does. That's what's required to do a good job. So, no. You are not describing a danger to his method. You are describing the result of people not doing their jobs.
No good manager would put his name to such management policies, even under a pseudonym, which at the end is trackable at least here.
IANAL but write like a drunk one.
I will refer you to Steve Jobs, which is one person that by all accounts could be described as creative.
On his first incarnation at Apple, he created the Macintosh.
It was a revolutionary computer and truly a design icon. But it was over budget and no clear strategy was thought to commercialise it. This iconic machine almost killed Apple and Jobs, rightly, was sacked before he would have wrecked the company.
When Jobs was back he put emphasis in doing the administrative parts of the work properly, introducing Japanese techniques of managing inventory for example.
Creative people need to understand that being creative is not the same as being bohemian and irresponsible.
There are creative people that are professional and responsible, and there are creative people that are a hindrance. A good manager should identify the later and work with them to become the former, but there is a limit for everything, and at some point obstructive people have to be given the push.
IANAL but write like a drunk one.
That is when you really need to document. In a year's time when you go back to that workaround, will you remember? Probably not. Put in a comment briefly explaining why you did a workaround or what external force prompted that choice.
As someone who has spent an awful lot of time documenting *other* people's code over the last few years, I believe I can offer some insight as to how it gets that way.
IMHO, the big reasons for poor documentation tend to be either related to the self-interest of the developer, or insufficient time being allowed by management to create the documentation. On the self-interest front, we have:
- Job security: If it is apparent that replacing a developer is going to be costly due to nobody else knowing the tricks of the undocumented code, nobody is going to put their hand up to be the one doing the firing, as the resultant disaster from the replacement getting up to speed is probably going to be blamed on the one who did the firing.
- Artificial inflation of worth: If a developer knows the secrets of the code but their coworkers do not, they tend to look considerably more efficient and productive than their coworkers when working on that segment of code. This is so common that it's almost easier to list the cases where it doesn't happen, than where it does.
- Politics and currency: Knowledge of the code has value, and withholding that from others gives it value that can be used to buy favours from other people, or used to "punish" people who cross them.
- Lack of visibility: Poor commenting and inaccurate documentation is often only really noticed by people with the technical background to understand it. If the developer answers to a non-technical person, they can choose to get lazy about the things they don't strictly need themselves.
- Revenge: If the developer leaves, the next guy is going to have a lot of trouble getting up to speed. By withholding documentation, the developer can make sure the impact is greater, and is really felt.
- Hiding bodies: If the code is hideously broken, and the developer incompetent or inadequately resourced, having no documentation allows them to hide this for as long as possible whilst they look for a way to get out of the organisation, reputation intact. Let the next guy take the heat.
On the management side:
- Lack of understanding: Sometimes management doesn't understand that if documentation (and code cleanups) and forever withheld, the codebase will become an unmaintainable mess. Simple changes start to take forever, and complex changes never fully work due to the need to hack them in.
- No time: Sometimes documentation becomes a "work in the background" thing, where no time is really ever allocated for it, until some disaster strikes, and the same people cry "but where was the documentation". Writing documentation (eg. technical documents) takes time, not only from needing to refer to and test the code, but also to verify and proofread the whole thing. It never happens in magical zero-time.
- Job security: Similarly to the developer's trick, management can do this too. If they hold knowledge about how everything fits together, and it's not written anywhere, then it's going to be hard to replace the *manager*, for the same reasons.
- Artificial inflation of worth: Let's face it, the manager's manager is probably never going to really read any technical documentation- they're too far removed from it all. Who looks better: The manager who delivers work in eight months, or the one who does it in nine, with proper documentation?
- Short-term focus: If the driving factors are always the externally visible ones, and internal concerns such as code maintenance are always neglected (perhaps because the manager won't explain the necessity of this to the higher-ups), then documentation *will* be neglected. If the manager plans to move on in the medium term, they may not care if the project falls over in a heap after they leave- it's unlikely anyone will pin it on them, and it may not matter anyway.
And a last one that's in a class of its own: Inability. Not everyone can write documentation well.
As long as there are annual reviews, and you want to look like superprogrammer, and the management (typically) doesn't give a F about comments, its in your interest not to document as much as possible, so only YOU can fix it. Then you look great when you find bugs that someone else has already spent 17 hours trying to figure out how your mystery code works, and you'll get the bonus and he won't.
And, of course, you want them to know they are in a big pile of doo-doo if they fire you, since you're _THE_ one that "knows" the code...
Its just another illustration of rewarding individual performance in a setting that is inherently a team effort. With everyone trying to look good individually, collaboration is priority #2.
Forcing devs to document code will accomplish this:
Summary: A method to add to numbers together
param a = a number
param b = a number
returns a number
bool AddNumbers( double a, int b )
{
return a - b;
}
Sorry, but when management focuses on process and places more emphasis on documentation rather then coding, be happy with the results you get.
I haven't thought of anything clever to put here, but then again most of you haven't either.
Have someone else comment your code.
If they can make sense of it to describe what it does, that's a good indicator it's decent code.
If they can't figure it out--big red flag.
Plus, they may find some bugs in the process.
Heated to red-heat.
Sounds good to me!
Birds are not dinosaur descendants;birds are dinosaurs, for all useful meanings of "birds", "are" and "dinosaurs"
In a situation where your company outsources code generation to some external IT consultancy, it might be beneficial for that external developer not to document his code. After all, who are they going to call when they need to understand the code or extend its functionality?
This also work down the road - if they should get several offers for future coding work in an RFP, the original programmer can still price very aggressively, as he knows all the pitfalls of the solution that he wrote in the past.
Aptly named variables are a good start. I had a grad student who came to me trying to debug fortran code (physics student). I took one look at it, and said: R1? S2? Before I will even look at this, go back and rename all your variables except loop counters to meaningfull names.
"But I know what they are."
"You may know, but I don't. And you are asking ME for help."
The clarity he found in renameing solved his problem.
If good code is worth documenting then try one or more of these:
1. Write the overview documentation BEFORE writing the code. This helps clarify the coding process. So documentation is about what you did, it's about what you are going to do.
2. Have another person review it. Does it make sense? Does the overview match the actual code?
For especially clever high production workers, you may have a documentor assigned full time to them. You hire a secretary to keep the boss out of trouble. Hire a documentor to keep up with the coder.
May be worth having a documentor for a team.
Third Career: Tree Farmer Second Career: Computer Geek First Career: Teacher, Outdoor Instructor, Photographer.
No, the OP is right. Not the programmers are setting the time line but the pointy-haired Bosses. They have to take documentation into account. But they give a shit about our estimates and are always asking that the work is done that little bit faster.
The private projects I do where time is of no concern are all perfectly documented.
I wrote a program for a software company (cannot name) that automated much of the documentation process. It took specs and replaced the future tense with the present tense as a first rough-cut. Most of it was pretty simple, actually. "X will load Y into Z" became "X loads Y into Z". The programmers actually enjoyed correcting the sometimes garbled English. Most importantly, it sped the process up 5x. I named the program "The Defuturizor" after ... well, if you can't figure that out, perhaps you should be defuturized.
cower in my shadow some more, feeb.
you're completely pathetic.
Why I didn't comment? Impossible deadlines where you just have to get the shit done fast in languages (like Java) not meant for getting shit done fast.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
cower in my shadow some more, feeb.
did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.
searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?
cower in my shadow some more, feeb.
you're completely pathetic.
I just write out an outline of what I want to do in my code first, in English. I put in notes about what tricks I think I can use, etcetera. I use a macro to convert each line of that outline into a comment in the format of the language I am working in. Then I write my code between all the comments. Voila! Commented code.
I find it a big help so I don't forget why I need to do what where.
Besides, when you start off by just writing out a line of code, your brain gets locked in to that line of code and you tend to write everything else around that first thought as expressed in code. When you are writing out an outline in English, it is psychologically easier to change your plans as the outline gets fleshed out. Your brain doesn't have to worry about syntax errors. It is just words. You can easily rearrange them.
Not that I am a professional developer, but I think it is just stupid to write code and then think you can come back later and remember everything about that code to put in appropriate documentation. Besides, when you force someone to put in documentation after the fact, how can you trust that they aren't just writing BS to fill up space to make you think they are doing their job. If they don't want to document their code then you should probably find someone else. They may be awesome at writing elegant code but what good is it if it can't be maintained? It becomes a minefield as soon as they quit for a "better" job.