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.'"

What?! Give them more money?

[L4t3r4lu5]

But money costs money!

Indians will appreciate your docs

[muon-catalyzed]

Once the boss learns about financial advantages of outsourcing.

Re:Indians will appreciate your docs

[Robert Zenz]

Upcoming next article: "How to get Indian companies to document the code I payed for?"

Recursive Logic

[jrq]

As I used to say "it was damn difficult to write, it should be bloody difficult to understand".

Re:Mandate works best

[Anonymous Coward]

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

// I dedicate all this code, all my work, to my wife, Darlene, who will
// have to support me and our three children and the dog once it gets
// released into the public.

// somedev1 - 6/7/02 Adding temporary tracking of Login screen
// somedev2 - 5/22/07 Temporary my ass

R.I.P - best question ever. [stackoverflow.com]

Re:Indians will appreciate your docs

[dintech]

And in our end-of-year special: "Why do my Indian offshore partners send back code that has Chinese comments in them?"