Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

How To Get Developers To Document Code

samzenpus posted more than 2 years ago | from the use-your-words dept.

IT 545

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

cancel ×


Sorry! There are no comments related to the filter you selected.

How to poke a dead body (2, Insightful)

alphatel (1450715) | more than 2 years ago | (#38684614)

It's called doing your job.

Re:How to poke a dead body (5, Interesting)

rufty_tufty (888596) | more than 2 years ago | (#38684742)

True but like it or not people don't do it. You can bitch that people should do it, but when they don't what then? You could fire them, but IME some of the people who write the best code by other metrics (reliability, bugs fixed, or just taking on a task no-one wants) are poor at documenting it themselves.
Do you fire people for not documenting code, discipline them? Is it worth fighting the battle if you just need to get the product out/fix the current problems/develop the next thing.
IME code quality always comes back to bite you, if you write bad code/undocumented then soon enough it will come back and bite you yourself when you come back to maintain/modify. If I don't provide documentation to others then I end up with more support requests so it's worth me doing that balancing act, it's not management's judgement call to make.
As for dealing with other people undocumented code, that's just a skill you need to have as an engineer, like being fluent in multiple languages many of which won't be your choice. You think I want this tool chain to be written in TCL? Should I then port it to my favourite language (e.g. perl) what if the next poerson to support it prefers python? It's just part of engineering that everyone else's code will look rubbish and undocumented to you. Even when it is documented you'll then think the documentation is overkill.
Yes it's rubbish, yes TFA makes some suggestions, some might work, some might not, but you can't just say it's your job to document and walk off, in real life we have to actually deal with problems and the reality that it doesn't happen as it should.

Re:How to poke a dead body (0, Insightful)

Anonymous Coward | more than 2 years ago | (#38684894)

It is their job.

If they don't do it, fire them.

If you can't fire them for some reason, give them crap reviews and crap tasks.

Carrot & stick.

I've run multiple dev teams. The stick was doing the builds for all the platforms that we supported ... like 10 of them. It took 4+ hrs. I had a histogram posted outside my office with the names of all the devs and usually the person who did the fewest builds got to do the next one. Simple. When someone screwed up in any way, they got to do builds for a week without any credit. Breaking the build on any platform meant you had to do the build for 2 weeks no credit. Breaking the build was terrible since it impacted 20 other people.

Comments for comment verbosity is worthless. Comments need to say more than what the code already says. I prefer function/method comments more. Explain what the function does for the program and user, not "this is a FFT function" - duh. Say what the input ranges need to be, how exceptions are thrown, if function pointers are used to call it (not easily found in code), etc. Things that are not obvious.

Oh, and no function should be longer than about 20 lines. If you can't see the entire function inside a single window, it is too complex and needs to be simplified.

If you think your code is beautiful and it has been a month, you are confused. All non-trivial code is crap and could be improved in some way. Therefore, the goal needs to be to make all your code appear to be trivial.

Re:How to poke a dead body (0)

Anonymous Coward | more than 2 years ago | (#38684978)

You sound like a fun guy to work with - if that included a carrot.

Re:How to poke a dead body (1)

Anonymous Coward | more than 2 years ago | (#38685168)

I write very little in the way of comments. Really only when for some silly reason I can't break stuff down into stupid simple components and have to do some hairy nested for loop or something.. or have to break convention in some way. The most common compliment I have received as a developer is that my code is easy for another developer to pick up, understand, and maintain. Most comments are a poor solution to badly written code. I've worked on projects that had stiff requirements regarding comments and penalties for not commenting. Invariably the comment loosely describes what a person intended to do during the first pass through of this code but it has since been refactored and updated numerous times and the comments are worthless noise.

Re:How to poke a dead body (1, Interesting)

gbjbaanb (229885) | more than 2 years ago | (#38685124)

no, you can keep badgering them to do their job properly, with the usual restrictions if they don't.

For example, what happens if coder A decides he doesn't want to use the company standards to write code, or he decides that writing the stock-keeping module is boring and works on an Android app instead? The same goes for not writing the support documentation to the minimum standard too.

I find that the process needs to say that no application is accepted as delivered until the minimum docs are supplied along with it. The docs should be enough that someone else can install it (as someone else usually does). Coders who don;t do the work properly get taken off their current code and put back on their old stuff until it's right. That includes the doc part.

Coders may thing they're some kind of elite, but they have to play according the the rules that are set by the company. If company requires docs, then docs is what they get.

So, yes, you're right that poor quality code bites you back, but that's still no excuse to allow guys who want to deliver the poor quality code and then let some other maintenance engineer maintain and support it (there are enough places where dev and maintenance are split tasks, this is bad IMHO)

Re:How to poke a dead body (2, Informative)

Anonymous Coward | more than 2 years ago | (#38684778)

It's called doing your job.

And if your job does't measure your comments as part of its "productivity metric"? Like companies that use 'Klocs' to see how much 'work' you've done?

Commnets aren't included when counting. So, it's quite clear that commenting code isn't part of the job.

Re:How to poke a dead body (5, Insightful)

Moryath (553296) | more than 2 years ago | (#38684944)

Indeed. The rise of "metrics for job performance" has caused a lot of pain for many sectors of IT.

Judging your programmers by "lines of code written"? Great. They'll write a solution with as many redundant lines of code as possible. They won't comment, because commenting doesn't count. Bugfixes will generally involve patch code that means more lines, rather than cleaning up the code itself.

Judging your IT support by "number of tickets cleared"? Great, you get just what people expect out of those @##$@#$ crapass "phone lines" that bank out of India or Malaysia; they'll do anything to get you off the phone as fast as possible and mark your issue "resolved", whether it is or not. Your in-house guys will have to triage: do we handle 5 "my flash isn't working and I can't watch youtube on company time" issues, or do we handle the issue for one person that's going to take ALL MORNING to resolve but since it's only one ticket, will red-flag us as "not getting enough done" according to The Almighty Metrics.

The Retardicans have started to try to put this into play in the education field, too - teachers' pay will now be dependent on the grades the kids get and their performance on certain tests. You can - as my mother has - put in 70 hour workweeks, staying after every day to tutor kids who have problems, seeking out specialists to help the couple of kids who actually may wind up diagnosed with a learning disability (example: one in particular can write at an 8th-grade level but can't seem to wrap his head around long division after 6 months of trying), trying to figure out what's with the others only to find out come P/T conference night that they aren't learning because they've internalized their parents' opinion of school as glorified daycare and therefore just don't want to pay attention - but the parents DEMAND that they be passed on to the next grade because it'll hurt Little Dumbass McAsswipe Junior's "self esteem" to be held back a grade. You can do all that and it WON'T MATTER, because the kids with learning disabilities won't be diagnosed for another 4 years, and there are enough Dumbass McAsswipe Juniors in the class to pull "the metric" down.

Re:How to poke a dead body (5, Insightful)

Eraesr (1629799) | more than 2 years ago | (#38685010)

Most of the time the problem doesn't lie with the developer. The developer who actively refuses to document is rare. In my experience, the real problem lies in managers not taking documentation seriously. It is caused by developers being under the stress of deadlines with a manager that really needs this piece of software to be finished yesterday. Managers just don't schedule in any time for documentation.

Another issue the article touches (and I really shouldn't have to say this because of course you have already thoroughly read the entire article. Twice) is that there's the question of when to start documenting, because software and APIs are often subject to change all the time, not in the least because managers keep asking for new or different features.

Personally, I often enjoy writing technical documentation. If I've written good portions of an API or framework that I'm particularly fond of, because it's all done oh-so-clever, you know, I enjoy committing the inner workings to paper to explain to my colleagues how it works and how it's supposed to be used. Unfortunately, like I said before, there often isn't any time to write good documentation and that's a real shame.

What?! Give them more money? (2, Funny)

L4t3r4lu5 (1216702) | more than 2 years ago | (#38684626)

But money costs money!

Re:What?! Give them more money? (1)

tbannist (230135) | more than 2 years ago | (#38684914)

According to the book "Drive", it's not really a good idea to pay extra to document the code. The reward will get a temporary bump in documentation but afterward the reward period ends, the documentation will be worse than before the reward was offered. That's because the reward will erode the intrinsic motivation to do a good job, and the monetary reward will solidify the notion that documentation is a noxious chore that they should be paid extra to do (alternatively, they may get the idea that if they don't document the code they can earn bonuses later for doing something they would normally get paid extra to do).

The best way to get better documentation is to treat your programmers like they are humans, pay them an adequate base salary and explain that supplying adequate documentation is part of their job, and that they can't do the job well if they're not providing the required documentation. Of course, this may require the manager to actually implement some processes like code reviews to provide timely feedback and reminders that documentation is needed. You might even have to, horror of horrors, refuse to accept new code that isn't adequately documented. If the programmers like their jobs, they'll be willing to make the effort to do it well.

Re:What?! Give them more money? (4, Insightful)

Moryath (553296) | more than 2 years ago | (#38685198)

Your entire premise rests on a few bad assumptions, however:

#1 - that the PHB will know what the fuck he is doing and adequately schedule enough time to document the code.
#2 - that the marketing fucktards will know what the fuck THEY are doing and not overpromise or promise delivery schedules so tight that the PHB has time to allocate to documentation in the first place.
#3 - that the company bosses are not "doing more with less" and overworking their employees to start with, relying on a down economy to fuck the working class by making everyone too scared to quit (for fear of not finding another job and being unable to support their families or being tied down by the risk of losing medical coverage) do 3-4 persons' jobs.

Now let me tell you how the "real world", the world created by the Retardicans for the last 15 years works:
- Employees ARE, as a general rule, overworked. The upper class HAVE, as a general rule, been playing the "do more with less" card so often that employees are doing the work that 5 years ago was done by 3 people.
- Employees ARE, as a general rule, fucked by the system. Need to find another job? Better hope it covers healthcare. The upper class don't have to give a crap about health care, the poor will never get out of people poor because if they ever did medical bills will put them right back, and the middle class lives in daily fear of losing health care coverage and being put into the poorhouse by medical bills - for themselves, spouses, parents, kids, anyone in the family.
- Managers are fucking assholes whose job it is not to work with the employees, not to ensure that enough time is allocated for things that need doing, but to be slave drivers. We just had a slashdot article covering the latest problem of people feeling too scared to take vacation because of how managers behave about it.

What we need are far stronger worker protections. The Retardicans have been screaming about "obamacare obamacare obamacare" like it's some kind of bogeyman, but actually, single-payer and guaranteed healthcare coverage are GREAT for the working class, because it's removing the iron ball of "healthcare tied to your asshole fucking boss" from their legs and will let more people actually look for better jobs, or even start their own businesses without the fear of one accident or one unexpected illness ruining their entire lives.

I like to use a big stick (2)

M4n (1472737) | more than 2 years ago | (#38684634)

Nothing else seems to work...

Re:I like to use a big stick (0)

Anonymous Coward | more than 2 years ago | (#38684700)

I like to use a big stick

As an incentive?
Filthy bastard!

Re:I like to use a big stick (2)

M4n (1472737) | more than 2 years ago | (#38684842)

They seem to like it

Re:I like to use a big stick (2)

Hognoxious (631665) | more than 2 years ago | (#38685180)

You're an Apple shop, right?

Re:I like to use a big stick (2)

robthebloke (1308483) | more than 2 years ago | (#38684770)

Just move the offending developer to another poorly documented part of the codebase. Repeat that a few times, and they soon learn why code comments are a good idea....

Mandate works best (2, Insightful)

Nickodeimus (1263214) | more than 2 years ago | (#38684636)

In this case, mandate works best because this is something that the developer SHOULD be doing anyways. Not documenting your code is inexcusable.

Re:Mandate works best (2)

netwarerip (2221204) | more than 2 years ago | (#38684756)

But in a small to midsized shop, undocumented code is akin to job security (in developer's minds at least).
If I had a nickel for every time I heard "Oh, be careful with what you say to (insert developer's name here), he is the only one that knows how the Widget process works." When I ask where the documentation is on it I get a blank stare, or worse, I get "Well, we asked him to do that but he says he's too busy."
Ok, maybe that's more of a sign of lazy, ball-less management, but it still sucks.

Re:Mandate works best (5, Insightful)

Anonymous Coward | more than 2 years ago | (#38685142)

Maybe it's a sign that the developer really is busy. Most places I've worked it's the developers who ask for additional project time to document code and aren't granted it because it's seen as a non profit generating part of the project (why have coders writing documentation for a finished project when they could be building the new project). It's shooting yourself in the foot for the future if you ever need to change anything in the code, but again, if that time is billable then efficiency savings from proper documentation are a very hard sell.

Re:Mandate works best (0, Flamebait)

Anonymous Coward | more than 2 years ago | (#38684758)

Mandate? You mean threaten them with a homosexual encounter if they don't comment their code?

Re:Mandate works best (5, Funny)

Anonymous Coward | more than 2 years ago | (#38684942)

* 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. []

Re:Mandate works best (0)

Anonymous Coward | more than 2 years ago | (#38685132)

My code is self documenting.

code documents itself (3, Insightful)

lynnae (2439544) | more than 2 years ago | (#38684644)

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.

Re:code documents itself (1)

Anonymous Coward | more than 2 years ago | (#38684880)

Your code should read easily. Developers making code complicated because they think it's smart just makes me cringe. But I disagree that comments are unneccesary. Comments should be there to explain the thinking of why something was done that way. Personally, I comment my code to remind myself when I have to come back to it. The fact it also makes the code easily maintainable is a bonus.

Re:code documents itself (1)

delinear (991444) | more than 2 years ago | (#38685174)

Indeed, there might be several different ways to achieve the same outcome with non-obvious advantages/disadvantages. No matter how elegant the code is, it tells you nothing about the reason for that particular implementation (say you're relying on a third party web service that's flaky or slow unless you format the request in a certain way).

Re:code documents itself (1)

slim (1652) | more than 2 years ago | (#38685178)

I think the way Uncle Bob puts it is that including a comment is an admission that you're unable to write code that's as expressive as you'd like.

*But* there's nothing wrong with making that admission. The flow is:

while(code can be made more readable within practical constraints) {
      make code more readable
if(code is readable enough to not require comments) {
} else {
      write a comment

Re:code documents itself (5, Insightful)

quintus_horatius (1119995) | more than 2 years ago | (#38684934)

In my experience, self-documenting code generally isn't.

Proper documentation never explains what you're doing - that's what the code is for. Documentation explains why you did the things you did, which is difficult to express in self-documenting code.

Re:code documents itself (1)

ifrag (984323) | more than 2 years ago | (#38684938)

I think the main problem is that some developers do not seem to realize WHEN the code can stand on its own, and WHEN having a bit of explanation is important. So the knee jerk reaction to this is just "we need more comments / documentation".

A lot of useless comments in completely obvious code adds absolutely nothing to the program, and in fact probably just makes it more difficult to read. A lack of comments in an extremely complicated algorithm or non-typical solution will probably result in someone breaking it later because they either think it is doing something else, or just don't get it.

Also, in terms of where it is located, I think developers are at least more likely to keep some description or outline in the code comments up to date, compared to say a separate document. So unless it is being sucked in from some automated tool like doxygen, I'd consider offline documents secondary to whatever is right in front of you.

Re:code documents itself (3, Insightful)

sgtwilko (472549) | more than 2 years ago | (#38684980)

I prefer the theory that well developed code is it's own documentation.

I'm a Very strong believer in self documenting code, I simply don't allow my team to create objects, variables, functions, etc that don't tell you what they do.

I'm also a strong believer in adding comments to code. Good, self documenting, code should tell you what it is doing without comments, but often the reason Why it needs to do things are is lost or cannot be conveyed in the code.

Well written code tells you what it does.
Well documented code tells you why it does what it does.

Re:code documents itself (1)

AmiMoJo (196126) | more than 2 years ago | (#38685060)

It amazes me how many programmers fail at the simplest of things, like putting units in variable names (engine_temp_c or battery_level_mv). If you can't write code that is readable and makes sense to others then you can't write code.

I disagree (4, Insightful)

acomj (20611) | more than 2 years ago | (#38685122)

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.

Re:code documents itself (4, Interesting)

apcullen (2504324) | more than 2 years ago | (#38685190)

If by "self-documenting code" you mean code with milti-paragraph long comments in it explaining in detail what each section does and how it's intended to work, with a detailed change log at the top of each section of the code, then I agree with you.
However IME to most developers "self-documenting code" means something more like "you should be smart enough to know how this works from reading my semi-descriptive variable names". I've seen comments like "Here's the main routine. This is fun" in some code that I've picked up and had to maintain. Made me shake my head at the time.
When I first started my career, I met a developer who put a comment on almost every line of his code. When I asked him why, he said, "because I try to code like the next person who's going to look at what I did is an idiot. And it usually is. It's usually me". I laughed at the time, but as I've grown older I've come to realize how true it is.

Indians will appreciate your docs (5, Funny)

muon-catalyzed (2483394) | more than 2 years ago | (#38684654)

Once the boss learns about financial advantages of outsourcing.

Re:Indians will appreciate your docs (4, Funny)

Robert Zenz (1680268) | more than 2 years ago | (#38684696)

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

Re:Indians will appreciate your docs (1)

Inda (580031) | more than 2 years ago | (#38684796)

Complete with spelling mistake!

That would be a Slashdot first!


Management issue (3, Insightful)

Anonymous Coward | more than 2 years ago | (#38684666)

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 ?

Re:Management issue (2)

Chrisq (894406) | more than 2 years ago | (#38684820)

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 ?

I've been there early on in my career. I had a tight deadline to produce something for the first iteration of testing. I said "its done but I need to document it. I was promptly told "we'll document it if we have any problems with it" and moved on to the next project.

Documentation good, comments bad (3, Insightful)

WillerZ (814133) | more than 2 years ago | (#38684670)

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.

Re:Documentation good, comments bad (1)

Anonymous Coward | more than 2 years ago | (#38684750)

As a scientific programmer I strongly disagree with you. Good code should of course be self explaining. But good comments are useful in describing why for example some complicated algorithms are used on some specific input data. From the code you should be able to understand how things are done. But for complicated issues you need comments on why things are done the way they are.

Re:Documentation good, comments bad (1)

CadentOrange (2429626) | more than 2 years ago | (#38684948)

He covered that in his exception. He says:

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.

Re:Documentation good, comments bad (1)

mattpalmer1086 (707360) | more than 2 years ago | (#38684822)

I completely agree that code should be clearly written - but this does not obviate the need for documentation.

Good documentation should explain the why of difficult design decisions. It should also explain the general contract the code is offering - e.g. whether nulls can be returned, or under what circumstances, what errors can be produced under what circumstances, etc. I really don't want to have to read and understand every little bit of someone else's code just to be able to use it productively.

On the flipside, I have seen a lot of completely useless documentation which just re-iterates what is already blindingly clear from the code itself.

Re:Documentation good, comments bad (1)

Anrego (830717) | more than 2 years ago | (#38684828)

I find general comments covering chunks of code to be useful when skimming through code, but agree that a lot of comments are redundant in well written code.

I definitely agree that higher level documentation is where it counts. I can read through a class and figure out what it does pretty quickly.. but figuring out how 100 classes interact is very time consuming. A quick little diagram can be invaluable.

Re:Documentation good, comments bad (4, Insightful)

K. S. Kyosuke (729550) | more than 2 years ago | (#38684878)

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.

They should be all forced to pass HtDP [] with all exercises done properly and I bet a lot of them would actually start writing quality code (both quality as in "less bugs" and quality as in "readable"). I love the Amazon comment where a CS PhD admits that reading the book actually taught him to write code properly.

(I have pretty much the same experience, having been subjected years ago to a typical "learn-the-syntax-of-Pascal-and-a-dozen-sorting-algorithms"-style first year of CS at my uni. But they never got around to teaching us how make your brain come up with code like the one in those nice textbook examples in the first place, what are the recurring code patterns (*not* design patterns, mind you). They have never ever once explained how to systematically go (for any problem in general) from a problem formulated in words to a working, readable code. Much like what Dijkstra about the contemporary math education - people memorizing proofs but having no idea how to "do math" in the first place, and teachers hand-waving every objection with saying that studens must "grow some intuition", but never explaining the processes involved explicitly. I believe I eventually got to the point where I started seeing the patterns, but explicitly formulated knowledge could have shortened the process by *years*. Go read the book, do the chores, see for yourself.)

Re:Documentation good, comments bad (5, Insightful)

djchristensen (472087) | more than 2 years ago | (#38685100)

If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.

This is a naive viewpoint that gets repeated over and over, most likely from people who've never actually implemented or maintained anything more complicated than "hello, world". As a developer I strive to write the simplest possible code (but no simpler!) to solve a problem, but often that code is complex enough or is based on some non-obvious assumptions (device drivers, anyone?) that I can't even remember later exactly why something was done the way it was. Sure, if you write code for relatively simple problems that don't have to interact with other complicated pieces (like the OS or any libraries), you might get away with little or no documentation within the code, but that's not the world I live in.

I do agree with others that external documentation is just as if not more important than internal comments. And while I'm very good with internal comments, I have to sheepishly admit I pretty much suck at doing the arguably more useful external documentation. Perhaps I haven't been adequately incentivised to do that, but then in most environments I've worked in, I get poked fun at for the level of comments I put in my code, not because they are excessive or unnecessary, but because most other code has almost no comments at all, so my code tends to stick out more than it should.

Re:Documentation good, comments bad (2)

Shavano (2541114) | more than 2 years ago | (#38685204)

Wrong. Comments should describe what programs are for, what assumptions it makes about parameters, classes, data structures, etc.

If you have to read complex program code to figure out what it does, you are in trouble.

Hire document experts (4, Interesting)

Maximum Prophet (716608) | more than 2 years ago | (#38684672)

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.

Re:Hire document experts (5, Interesting)

lkcl (517947) | more than 2 years ago | (#38684810)

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.

it's funny you should mention this, because somewhere about 3 years ago wasn't there a slashdot article about some entrepreneur who didn't hire computer science majors (this was the U.S...) he hired english language majors and then trained them to program?

the end-result was that he got people who produced better results because they were better able to express themselves and had already been trained to handle and comprehend more complex structures than people who thought they could program.

Re:Hire document experts (1)

Monchanger (637670) | more than 2 years ago | (#38684930)

Trained them to program? English majors? I'm having flashbacks to yesterday's CodeAcademy story.

Re:Hire document experts (2)

ciderbrew (1860166) | more than 2 years ago | (#38684958)

That reminds me. Must get a gymnast for a mistress.

Re:Hire document experts (0)

Anonymous Coward | more than 2 years ago | (#38685090)

When all you need is code monkeys who do not ask questions, then perhaps that is a good choice.

Don't Accept (4, Informative)

Aladrin (926209) | more than 2 years ago | (#38684676)

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

Re:Don't Accept (4, Insightful)

dkleinsc (563838) | more than 2 years ago | (#38684790)

You also need a culture that encourages documentation as well. I've met plenty of developers who are thoroughly convinced that the code is the only documentation that anyone would ever need. Here's the problem with that thinking:

void frob_the_splutnik(int a, int b) {
            s = get_splutnik()
            s.frob(a, b)

That's definitely concise, and perfectly clear, but only if you already know what a splutnik is or why you'd want to frob it, and what a and b are supposed to signify. If you're a developer unfamiliar with this code base though, you have no clue what this means, not because you're dumb but because you've never encountered any of the concepts that the original coder had in mind.

Re:Don't Accept (0)

Anonymous Coward | more than 2 years ago | (#38684962)

Unfortunately documented code often looks like this:

// this code frobs a sputnik
void frs(int a, int b) {
s = get_sp(), b)

Re:Don't Accept (0)

Anonymous Coward | more than 2 years ago | (#38685064)

Which makes matters even worse because the code actually frobs the splutnik not the sputnik

Re:Don't Accept (1)

Anonymous Coward | more than 2 years ago | (#38684806)

Quote from unknown source: It's called peer review only if the developers dislike each other. It's called pair programming otherwise.

Re:Don't Accept (1)

Aladrin (926209) | more than 2 years ago | (#38685150)

I've heard that before and find it funny, but Pair Programming is actually a step beyond. It includes automatic peer review as part of it's process, but goes further.

I've personally found PP to be of use in certain circumstances, but generally prefer not to use it. Peer review, however, remains valuable all the time.

As they say.. (0)

Anonymous Coward | more than 2 years ago | (#38684692)

Don't document your code. But code your documentation.

Apart that, i disagree on the 'financial' motive as suggested. The real solution is to reduce the pressure. Increasing pressure by putting a bounty will slap back in your face in the long run. And hard.

Realistic Deadlines (0)

Anonymous Coward | more than 2 years ago | (#38684710)

Being realistic about the deadlines goes a long way to getting developers to do their commenting as they go. If your developers are having to work 50+ hour weeks to get the code out of the door as it is then there really isn't much of an incentive for them to add to their workload, no matter how big your carrot or stick as there comes a point where no amount of money can replace having a life outside of work.

Make sure your quotes contain adequate time to both write and document the code and don't expect the developers to pick up the slack with their free time.

I've done it. All of it. (1)

vikingpower (768921) | more than 2 years ago | (#38684712)

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.

Time... (0)

Anonymous Coward | more than 2 years ago | (#38684716)

How about managers allow sufficient to write documentation? (Instead of "get it out the door")

Recursive Logic (2, Funny)

jrq (119773) | more than 2 years ago | (#38684722)

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

Re:Recursive Logic (1)

Migala77 (1179151) | more than 2 years ago | (#38684970)

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

used to say when you still had a job?

Re:Recursive Logic (1)

jrq (119773) | more than 2 years ago | (#38684994)

Yes. I when I still had that, AND a job.

Documentation not always worth it (4, Interesting)

DoofusOfDeath (636671) | more than 2 years ago | (#38684724)

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.

Re:Documentation is usually worthless (0)

CadentOrange (2429626) | more than 2 years ago | (#38684932)

I would go so far as saying that documentation of non-public APIs (i.e. stuff that is only used by the same team) is worthless as it rapidly gets out of date, and it takes an insane amount of effort to keep it up to date and correct.

Keeping the documentation up to date requires additional effort and time, which means less time for writing code and unit tests. This much is self-evident as is the result: each piece of work takes longer to deliver.

Ensuring the documentation is correct and up-to-date is impossible. There are loads of tools that will help you improve the quality of your code. Static analysis tools, unit tests and code coverage tools, and the good old QA department to name a few. No such tools exist to ensure the quality of your documentation. Additionally, as documentation does not get executed as part of the build/unit-tests/QA tests there is no way of ensuring that the documentation isn't flat out wrong (nevermind ensuring that the documentation is "correct").

On most projects, sensible class/method/variable names help reduce the need for documentation. Properly written, comprehensive unit test coverage all but eliminates the need for documentation. Want to know how to invoke a particular piece of code? Look at the unit tests. Want to know what this option does? Look at the unit tests. Want to know the behaviour of a piece of code given a certain parameter? Look at the unit tests. Want to know all possible values for a parameter? Look at the unit tests.

The only time you ever want to have comments is to explain what a piece of non-trivial, non-intuitive piece of code does.

TLDR version, properly unit tested code rarely ever requires accompanying documentation. The fact that the author of the article FAILS to mention unit tests just shows that he's spent far too little time writing code and far too much time writing stupid fluff pieces like this for PHBs.

Code Reviews and include in Job Description (2)

realsilly (186931) | more than 2 years ago | (#38684728)

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.

Re:Code Reviews and include in Job Description (1)

L4t3r4lu5 (1216702) | more than 2 years ago | (#38685094)

Be honest, you don't want to lose your job while your well documented code is shipped to an Indian man-farm in a cost-saving (read: Bonus increasing) exercise, so you don't.

Y'all made your bed.

Surely I'm not the only one (3, Interesting)

AdrianKemp (1988748) | more than 2 years ago | (#38684772)

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.

Re:Surely I'm not the only one (2)

Assmasher (456699) | more than 2 years ago | (#38685074)

This is why you "document your code" as you write it.

There's no reason you can't document your code as it is being written, in fact, it's the best time to do it because the documenting the *reason* you choose to do something a particular way can actually be more important than ensuring that the following code is easy to follow.

There are, of course, limits to what you should document in code. For example, I wrote a software renderer in Java two years ago and there is a section that relies on some hidden surface removal techniques covered well in Abrash's book(s) but very complicated to explain in the level of detail that any software engineer would understand because explaining it relied on a corpus of knowledge not common to software engineers. My documentation in the code explained it rudimentarily and then pointed anyone else reading it to some references for greater understanding. That was the one place in the code I did that, and it was the first time I've done that in code comments before.

BTW, it is quite often more valuable to give your variables and arguments clear names that intimate their usage and intent than over the top code commenting - but it all helps.

float[][] m_aHiddenSurfaceRemovalScanlineFragments_Z;

is much more clear than

float[][] m_aHSRFragsZ;

(Ignoring our Hungarian notation approach of course)

BTW, names like that can be a lot of typing, so we usually write, build, test, validate, refactor for clarity, then check-in.

What carrot? (1)

TrashGod (752833) | more than 2 years ago | (#38684776)

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.

Anatomy of a documented method (4, Insightful)

Ouija (93401) | more than 2 years ago | (#38684792)

// WHY
int WHAT(...) {
      return HOW();

too much formulaic crap (2)

dltaylor (7510) | more than 2 years ago | (#38684818)

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.

Give 'em incentives (1)

El Solitario (2552408) | more than 2 years ago | (#38684830)

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.

We already know the answer. (1) (1238654) | more than 2 years ago | (#38684852)

But we also know that nobody here or their managers are going to accept it and follow through, so why bother having the discussion?

Ah, I know the answer to this... (1)

3seas (184403) | more than 2 years ago | (#38684856)

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.

It's all time and pressure (0)

Anonymous Coward | more than 2 years ago | (#38684860)

IME, few places value well-documented code. There is usually a tight schedule and some unexpected changes. (Yeah, Agile is supposed to fix this, but comments don't pay the bills, so there's always business pressure to just do the code). Add to that the threat of outsourcing, done badly ( as most American companies do it), and there is little upside to well-documented code to a developer in the trenches.

As for making it easier to debug and deal with support issues, well, those are not development costs in most companies, so they are not in the discussion.

Real answer not the BS answers they give.... (1)

Lumpy (12016) | more than 2 years ago | (#38684868)

You want us to document our code? then GIVE US TIME TO DO SO.

Documentation takes time, I cant do it magically.

next to relevant (1)

Tim4444 (1122173) | more than 2 years ago | (#38684920)

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.

Management problem, not programmer problem (1)

Dcnjoe60 (682885) | more than 2 years ago | (#38684940)

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.

design document vs. documenting source code? (3, Interesting)

us7892 (655683) | more than 2 years ago | (#38684952)

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 :)

Easy Math (0)

Anonymous Coward | more than 2 years ago | (#38684956)

If a project should cost me 8 hours to do well and 1 hour to document and you give me 4 hours to finish it, you get bad undocumented code.

Waste of time (1)

Yuioup (452151) | more than 2 years ago | (#38684960)

Documentation is a waste of time. You're better off writing your code cleanly so that somebody else can decipher it easily.

The problem isn't the "programmers" it's managers (1)

Assmasher (456699) | more than 2 years ago | (#38684974)

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.

It's A Question of Honor (2)

Gallenod (84385) | more than 2 years ago | (#38684988)

"What!?! Comment my code? You question my honor! I'll kill you where you stand!"
-- Mukluk, Klingon Programmer

Fire them if they don't (1)

echusarcana (832151) | more than 2 years ago | (#38684992)

No comments. No paycheck. It is pretty simple.

Re:Fire them if they don't (3, Insightful)

BVis (267028) | more than 2 years ago | (#38685140)

I hope to $deity you're not a manager. Your morale must be terrible if you do.

I have to echo other commenters: If you want well documented code, you need to allow sufficient time for said documentation to be written. Failure to do so isn't a failure in programming, it's a failure by management to build realistic timelines based on feedback from programmers.

If your programmers are constantly telling you they need more time, on project after project after project, and it's ALL of them, not just a few complainers, then you need to look in the mirror to find the source of the problem. Go to sales/marketing, read them the riot act about promising impossible deadlines, and get THEM fired if they continue to promise unicorns on a wombat budget.

Easy! (0)

Anonymous Coward | more than 2 years ago | (#38685006)

I use only documented technologies.

Example: The whole Typo3 documentation could be thrown away if they had used XSL instead of doing their own thing.

1) End user asks me something
2) I spit out a link
3) ...
4) End user GTFO


I love documents... question documenting code (1)

scamper_22 (1073470) | more than 2 years ago | (#38685008)

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.

Pair programming? (0)

Anonymous Coward | more than 2 years ago | (#38685018)

Have you tried pair programming? Having multiple programmers working on a same code means that they need to coordinate. They get to talk/write down stuff for each other. It is even better if programmers are separated by a few time zones ... after you are woken up at 3am by a phone call just because some simple stuff wasn't documented, you will preemptively document staff.

Docuentation Managers? (1)

StewBaby2005 (883886) | more than 2 years ago | (#38685020)

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"

Literate Programming as opposed to Illiterate (1)

WillAdams (45638) | more than 2 years ago | (#38685028)

Send your programmers this link: []

and have them read this book: []

``Propaganda'' here: []

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.

Tell Them Other People Will See It (1)

Cryophallion (1129715) | more than 2 years ago | (#38685048)

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.

And BTW this is not documentation (1)

nirgle (554262) | more than 2 years ago | (#38685052)

// Close the stream

Catch 22 (2)

Kjella (173770) | more than 2 years ago | (#38685056)

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.

pft (-1)

Anonymous Coward | more than 2 years ago | (#38685076)

Good luck picking sides in a race war.

Simple solution (2)

msobkow (48369) | more than 2 years ago | (#38685102)

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.

Don't document your code ! (2)

eulernet (1132389) | more than 2 years ago | (#38685156)

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 ?

make them troubleshoot it (3, Interesting)

misfit815 (875442) | more than 2 years ago | (#38685194)

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.

Programmers != Software engineers (2)

ktrnka (2015104) | more than 2 years ago | (#38685200)

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.
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?