×

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!

The Importance of Commenting and Documenting Code?

Cliff posted more than 8 years ago | from the worthwhile-software-engineering-practices dept.

Businesses 203

mrtrumbe asks: "The company I work for is in the process of creating a development standard to be applied to all projects. The topics being considered range from dictating the formatting of the code (an issue on which there is widespread agreement), to creating a standard for commenting and documenting the code (a far more contentious issue). On the issue of commenting and documenting, there are two extreme views being considered with most employees' opinions falling somewhere between them." To comment, or not to comment. And if you do choose to comment, what's the best way to standardize it, company-wide?"The first view is that commenting and documentation will protect the firm from bad programmers or a programmer abruptly leaving, make the code far easier to understand to someone unfamiliar with the codebase, and are necessary for all public, private and test code. The opposing view is that there are more effective ways to mitigate the risk of bad and disappearing programmers (like mandated shared ownership of code and sufficient oversight), that comments are not necessary for clarity and can be dangerous if not kept up to date (which is considered likely), and that documentation is necessary only for public code. Where does Slashdot stand on this issue? Please share any success stories and recommendations for a company-wide standard on commenting and documentation of code.

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

203 comments

doxygen (1)

Intron (870560) | more than 8 years ago | (#14428068)

We just got rid of our out-of-date function headers and replaced them with doxygen-style comments. The function parameters, return values and called-by / calls information will now stay up to date, and the html reference output is handy.

Re:doxygen (2, Informative)

baadger (764884) | more than 8 years ago | (#14428937)

Doxygen [stack.nl] is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

No Perl? :(

Re:doxygen (2, Informative)

Randolpho (628485) | more than 8 years ago | (#14429312)

Doxygen is nice because it standardizes a particular commentation style over multiple languages, so that whatever you use for a project (or within a project), you comment in roughly the same way, using the same commands, etc.

Personally, however, I very much prefer the xml-oriented way of doing it found in Javadoc and .NET's comment/documentation scheme.

Re:doxygen (1)

renehollan (138013) | more than 8 years ago | (#14430002)

Heh.

I once suggested this, at least for new code, at a former employer in Canada, was backed up by all other devs who would have to use it, and got the ideas shot down by our boss because he could not see the value in it over the cost of learning a new way to annotate code to be doxygen-friendly.

Sigh.

I didn't stay there very long.

Are you mad? (3, Funny)

voice_of_all_reason (926702) | more than 8 years ago | (#14428072)

Never comment your code. That way everyone needs to ask you for a fix when thinks break. Think of it as "employment insurance..."

Re:Are you mad? (1)

indifferent children (842621) | more than 8 years ago | (#14428784)

No, feel free to comment your code (random gibberish works fine). But whatever you do, do not *read* comments in code and expect them to have any bearing on reality. Even if the comments accurately describe what a program was written to do (rare), someone will have changed the code and not the comments, or the comments and not the code. Save yourself a lot of time and asprin; if you want to know what the code does, read the code.

Don't comment or document (0, Redundant)

youngerpants (255314) | more than 8 years ago | (#14428082)

For Gods sake man, you're just making so that you are easily replaced. Real men don't comment or document their code; instead we sit in high priced development contracts performing application support.

Re:Don't comment or document (1)

Bazzalisk (869812) | more than 8 years ago | (#14428254)

You still have a lot to learn on this subject.

Real men comment their code misleadingly - which is much more confusing than no comments at all.

Re:Don't comment or document (2, Funny)

the eric conspiracy (20178) | more than 8 years ago | (#14428837)

Not only write misleading comments, but also write variable and method names both generically and misleadingly too. For example:

ArrayList aStrPtr = new ArrayList()

If you are writing in C or C++ use macros to transform your code to look like another language, but incorrectly:

#def begin: }

#def loop: if

and so on

Documentation (3, Informative)

bloodredsun (826017) | more than 8 years ago | (#14428083)

A brief decription of the object/class and then simple comments on any methods. That's a minimum but I would also go for single line comments for conceptually difficult peices of code that you know you will forget in a couple of weeks. Not overly rigorous but easy enough that people do follow it.

A good model for me would be the Java SDK docs and the javadocs tool but that's just me.

Re:Documentation (5, Insightful)

anomalous cohort (704239) | more than 8 years ago | (#14428436)

In addition, consider the following points.

  • Code comments are only one form of developer documentation. Other forms include design and discovery docs (e.g. UML) and change comments (e.g. this change fixes bug 2938). Put design/discovery docs in an Intranet collaboration site. Wiki or any CMS such as Plone are good technologies for this. Put change comments in your source code control system.
  • Code comments should answer why, not what. As stated elsewhere, commenting is not a replacement for compentency. Any compentent developer can read most business application style programming and figure out what is going on. What you cannot read from the code was that meeting where some influential user or other relevant stakeholder insisted on a certain approach or placed high value on a certain outcome.
  • Code comments should not insult the intelligence of your average programmer. If you are coding a simulated annealing or genetic programming algorithm, then providing a URL to the appropriate material in the code is sufficient. If you are looping through some recordset for search or data aggregation purposes (which is about 90% of your business application coding), then you don't really need to provide a comment to the affect that that is what you are doing.

mod parent up (0)

Anonymous Coward | more than 8 years ago | (#14429082)

Code comments are only one form of developer documentation. Other forms include design and discovery docs (e.g. UML) and change comments (e.g. this change fixes bug 2938). Put design/discovery docs in an Intranet collaboration site. Wiki or any CMS such as Plone are good technologies for this. Put change comments in your source code control system.


If you fix a minor bug, and a week later you realize it's created a major bug, but in the meantime eight dozen commits have been made by your team, it's not always easy to just roll back to the version before the one you helpfully noted in the CVS comment as being "the" bug fix; you really do need to tag bug fixes in the code itself. The more documentation, the better. Explaining the "fix" you made should be part of this, though it can be out of the code itself, in external docs -- as long as everyone knows that that's where to it, and it's not split among five different places. That's where standardization really would be helpful. Some people still only comment in CVS, and I think that's just not enough if it's a team project.

mod parent up # reposted as me (1)

Artifex (18308) | more than 8 years ago | (#14429127)

Code comments are only one form of developer documentation. Other forms include design and discovery docs (e.g. UML) and change comments (e.g. this change fixes bug 2938). Put design/discovery docs in an Intranet collaboration site. Wiki or any CMS such as Plone are good technologies for this. Put change comments in your source code control system.


If you fix a minor bug, and a week later you realize it's created a major bug, but in the meantime eight dozen commits have been made by your team, it's not always easy to just roll back to the version before the one you helpfully noted in the CVS comment as being "the" bug fix; you really do need to tag bug fixes in the code itself. The more documentation, the better. Explaining the "fix" you made should be part of this, though it can be out of the code itself, in external docs -- as long as everyone knows that that's where to it, and it's not split among five different places. That's where standardization really would be helpful. Some people still only comment in CVS, and I think that's just not enough if it's a team project.

# hah. I screwed that one up. What a perfect example of why commenting is important :)

Re:mod parent up # reposted as me (2, Insightful)

anomalous cohort (704239) | more than 8 years ago | (#14429792)

I see your point regarding using source code control for change comments. The issue that I have run into putting change comments in the code itself is one that also happens over time and multiple changes.

Here is an example, let's say you change line 188 to fix defect 2287. Next week, another developer needs to change the same line to fix defect 3012. Does that developer append on to your comment or overwrite your comment? What if the developer completely changed line 188 so that your changes were lost?

I guess that there is no perfect answer so you end up putting change comments in both the code and in the CVS (or similar) system. The downside of that is the wasted resources and potential for error in duplicitous effort.

Fit-for-Purpose (1)

redelm (54142) | more than 8 years ago | (#14428107)

The problem with standards is they confound things and treat them similarly. Each [software] project has different goals, expected lifetimes, maintainability and communications concerns. And sometimes subsections are different.

About the only thing a good standard will do is present options, advantages and disadvantages, and require that an explicit decision be made after appropriate discussion.

more standards... that'll fix it! (4, Insightful)

yagu (721525) | more than 8 years ago | (#14428125)

Stop it! Stop it! Stop it! The Noise. Make it stop!

No, seriously, you cannot comment your code and enforce that as policy. You can't impose standards and impose enforce that! It doesn't work.

You either know how to program/code, and commenting is part of that, or you don't. Either your staff knows same or doesn't.

Go ahead and establish "guidelines", you'll feel better. But I've been in this industry for over 20 years and applying "standards" for coding and "comments" has never worked.

Write un-obfuscated code, have peer reviews and walkthroughs, and have staff that know how to create... It's really all you need.

(As an anecdotal experience -- we had "standards" on a major project, and I accidentally created a Class without the proper capitalization. A peer came to me and confronted me on said transgression and wondered what I intended to do about it. I said I intended to let it slide and would try to be better in the future. He insisted we "fix" this problem and we spent (and I'm NOT making this up!) the next day's worth of time re-factoring the code (the IDE wasn't up to speed for this -- thanks Microsoft) to "correct" the "problem". Sigh)

Re:more standards... that'll fix it! (4, Informative)

oni (41625) | more than 8 years ago | (#14428282)

You either know how to program/code, and commenting is part of that, or you don't. Either your staff knows same or doesn't.

Spot on!

Write un-obfuscated code, have peer reviews and walkthroughs, and have staff that know how to create... It's really all you need.

*stands up and cheers*

I totally agree. You can't take someone who is, frankly, lazy and selfish - and that's what we're talking about here. Anybody can write code. When you write a comment, you are doing more than coding, you are developing a product, you are making sure that product is maintainable. You are helping people who will come after you, maybe years later, people you'll never meet. People who flat refuse to think that way are lazy and selfish - you can't take someone like that and make them comply. They are worthless. Just fire them.

You need a business culture that values documentation. You need people who have maintained someone else's code. Those kind of people understand and care. The kind of people who have only ever written new stuff don't get it. They don't understand why this is important. They don't realize that the wiz-bang program they wrote today will have to be thrown away in a year or two when the boss asks for just one little button to be added. It will have to be thrown away because it'll be cheaper to rewrite it than to decode it and add the button. Some people just don't get that.

Look, commenting is not rocket science. You don't need strict rules. A comment is a communication with someone in the future. It's like a time capsule. You just need to comment things when it's reasonable to think that a person looking at the code might need help. You don't need comments like //add one to x and store it in x. But you might need a comment like, //increment x because this procedure pushs the stack.

In an interview with a prospective programmer ask the following question: "what is the most expensive part of the development lifecycle" If they say anything else except maintenance, don't give them a job. They don't get it. They aren't going to do it.

I also want to add something to the story, where it says this:
dictating the formatting of the code (an issue on which there is widespread agreement)

I was thinking, "yeah right, there is widespread agreement on the idea, but when you sit down and try to do it you'll find widespread disagreement." Everybody likes the idea of forcing the other programmers to write code the same way that you do. Nobody likes the idea of having to write code a certain way. Where I work, there was widespread agreement too, but we never got past the issue of capitalizing the first letter of functions. Seriously.

If I had to do it again, I would get some premade coding standards. Creating your own is too hard.

Re:more standards... that'll fix it! (1)

codeboost (603798) | more than 8 years ago | (#14430395)

Documentation is important, but it shouldn't be the only reason for hiring or firing programmers.
Many smart programmers tend to be ego-centric and/or megalomaniacal with a set of strange beliefs. For instance, some exceptionally smart hackers think that good programmers should read the code, not the comments.
Although they don't write good comments, these are the guys you want to have working for you.
But then of course, it depends on the project.
Not all tasks require genius hackers with a personality disorder.
Laziness and selfishness are not determined just by how many comments programmers write, but by the quality of their job.
Just my opinion.

Re:more standards... that'll fix it! (1)

SlayerDave (555409) | more than 8 years ago | (#14428307)

He insisted we "fix" this problem and we spent (and I'm NOT making this up!) the next day's worth of time re-factoring the code (the IDE wasn't up to speed for this -- thanks Microsoft) to "correct" the "problem"

I call bullshit. Visual Studio is easily capable of doing a find-and-replace over the entire project (try CTRL-H). It shouldn't have taken you more than 30 seconds to fix this problem. If you spent the entire day "re-factoring" then you obviously had more serious problems than a simple deviation from the capitalization standard.

Re:more standards... that'll fix it! (1)

Wisgary (799898) | more than 8 years ago | (#14428637)

definitely fucking agree, wtf, an entire day just doing a find and replace? Even if it was a common word that could be contained in other lines of code and you had to manually look for it, clicking next next replace next replace etc etc, and it was a HUGE project, if you did a find and replace across it, it shouldn't take an ENTIRE DAY.

Re:more standards... that'll fix it! (1)

Trepalium (109107) | more than 8 years ago | (#14429745)

Unless it was in source control, where you had to take a lock on each file you wanted to modify. Getting locks released on the various files you needed to change could take a good amount of time depending on how easy it is to track down the lock owners.

Re:more standards... that'll fix it! (1)

carlos92 (682924) | more than 8 years ago | (#14428479)

Better make it a standard to document/peer review designs, specially if you are doing OOD/OOP. You DO design before you code, do you?

Re:more standards... that'll fix it! (1)

badfish99 (826052) | more than 8 years ago | (#14428789)

The company I work for has a "standard" that says "every method you write must have a comment".
So our code has hundreds of methods called things like getFoo() and setFoo() with comments like "this returns the value of foo" or " this sets the value of foo".
By the time you've written all these useless comments, you're too tired to write a single useful comment that explains how the code works.

In any case, code is always obvious when you've writing it. So it's hard to know what comment would be needed to make it clear to someone who wasn't familiar with it. Maybe comments should always be written by someone other than the author of the code?

Re:more standards... that'll fix it! (1)

PianoComp81 (589011) | more than 8 years ago | (#14430184)

The company I work for has a "standard" that says "every method you write must have a comment". So our code has hundreds of methods called things like getFoo() and setFoo() with comments like "this returns the value of foo" or " this sets the value of foo". By the time you've written all these useless comments, you're too tired to write a single useful comment that explains how the code works.
There are programs out there for auto-commenting get/set methods. Heck, there are programs that'll create basic get/set methods from your class variables and comment the functions at the same time.
In any case, code is always obvious when you've writing it. So it's hard to know what comment would be needed to make it clear to someone who wasn't familiar with it. Maybe comments should always be written by someone other than the author of the code?
Instead, write your code, comment as you think it should be, and then send it out via e-mail for review. If you don't have enough comments, you'll get e-mail back saying "this needs comments here, here, and here". It works well. Usually, you don't have to change anything, but every once in a while, you miss a comment or something you think is obvious is not obvious to others.

Re:more standards... that'll fix it! (1)

Mr. Slippery (47854) | more than 8 years ago | (#14430383)

In any case, code is always obvious when you've writing it.

Hmm. What field do you work in where you always write trivial code?

Re:more standards... that'll fix it! (2, Insightful)

WGR (32993) | more than 8 years ago | (#14430819)

In a proper software project, comments are written before the code so they should not be written by the coder. They should reflect the block of the system design that the routine implements, the assumptions made during design etc. It should capture the design so a maintainer can avoid changing the design unintentionally.

A comment should be there to tell a future maintainer why this code exists, what was the intent and its reason for existence. It does not exist to tell how the routine is implemented, so it should seldom have action verbs.

The other useful kind of comment is the expansion of variable type declaration that describes the constraints on a variable that are not expressible in code.

Are you serious? (5, Interesting)

zhobson (22730) | more than 8 years ago | (#14428138)

If your code is not commented it's not complete. My advice is to fire every developer that doesn't think that comments are necessary.

Re:Are you serious? (2, Insightful)

Rakshasa Taisab (244699) | more than 8 years ago | (#14428545)

Ops, you just lost all the developers who manage to write code that is so clear it doesn't need comments.

Re:Are you serious? (3, Insightful)

NathanBFH (558218) | more than 8 years ago | (#14428647)

For significantly complicated projects, those programmers don't exist. If you think commenting your code is an unreasonable job requirement, I will fire you.

Re:Are you serious? (2, Insightful)

gnovos (447128) | more than 8 years ago | (#14428994)

For significantly complicated projects, those programmers don't exist. If you think commenting your code is an unreasonable job requirement, I will fire you.

I have yet to see a project, in 11 years of coding, that is so complex that comments are a REQUIREMENT. If you don't know how to refactor, and how to reduce your bloated thousand-line long methods into a series of simple to understand 10-line long methods, you still have much to learn about good code.

Re:Are you serious? (2, Insightful)

Randolpho (628485) | more than 8 years ago | (#14429257)

Even if you're the best normalizer/refactorer (is "refactorer" a word?) in the world, you had better explain what a function or method or class or aspect or (etc..) does, how it's used, and what the expected results are, or you have made code that is a nightmare to maintain.

In truth, function-point comments of a well-normalized/refactored program represent easily 99% of the necessary commentation for a program. The only time you ever really need comments otherwise is to explain a particularly tricky algorithm that, say for performance reasons, must resist typical normalization/refactoring. Even then, you can easily place an overview of the algorithm in the documentation (or reference a whitepaper), and again remove most of your inline comments.

As for function-point comments/documentation, I suggest something like Javadoc, C#'s Intellidoc, or some similar platform like doxygen, although if you're manly or insane enough, you can always maintain the documentation separate from the code.

Re:Are you serious? (2, Insightful)

gnovos (447128) | more than 8 years ago | (#14429440)

Even if you're the best normalizer/refactorer (is "refactorer" a word?) in the world, you had better explain what a function or method or class or aspect or (etc..) does, how it's used, and what the expected results are, or you have made code that is a nightmare to maintain.

That is what your automated tests are for! No comment in the world is better than a test showing exactly how a method works, what expected inputs and outputs are, and *proving* that what you think it should do is what it actually does. The great thing about proper automated tests, they can NEVER go out of date and still pass.

Re:Are you serious? (1)

Metasquares (555685) | more than 8 years ago | (#14429582)

Don't assume that everyone who will read the code will want to figure out what the tests are doing as well.

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14429664)

Of course they will, if they want to use it properly. Why assume somone will read comments but not read the tests?

Re:Are you serious? (2, Interesting)

Metasquares (555685) | more than 8 years ago | (#14429763)

The same reason that some people only read half of a long email: They think they've read "enough" to get the "gist" of it, even if they miss something like "your default password is your last name" at the bottom. Ideally, you probably want an explanation of what the code does as near to the code itself as possible.

I had a friend who used to refer us to his tests whenever we had a question about his code. They were his only form of documentation. He didn't believe in submitting the tests with the program itself or sharing them with other developers, so no one could ever understand what he was doing. Unsurprisingly, when it came time to integrate his code, whole projects fell apart because no one could figure out how to cleanly integrate his code into the logic of the larger program.

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14430156)

He didn't believe in submitting the tests with the program itself or sharing them with other developers, so no one could ever understand what he was doing.

Come on, there is no way any sort of documentation could have helped this kind of problem... If he isn't willing to submit his tests, what chance is there he'll submit his documentation?

Re:Are you serious? (2, Interesting)

AuMatar (183847) | more than 8 years ago | (#14429963)

And here is one of the reasons the agile method people get so much wrong. Automatic tests are not documentation, by any means. They do not prove that code is correct, or bug free. A test proves that for some input, a certain output was generated. Thats it. It doesn't explain why that output was generated, why that case was important, what other cases might be important, how those test cases were chosen, or explain the logic used to generate that output. For that you need documentation- either in code or out of code. Automatic tests have their place, but they are not equal to design or documentation. Any place that uses them as such is producing shitty software which will bite them on the ass when the original devs leave.

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14430140)

And here is one of the reasons the agile method people get so much wrong. Automatic tests are not documentation, by any means. They do not prove that code is correct, or bug free. A test proves that for some input, a certain output was generated. Thats it. It doesn't explain why that output was generated, why that case was important, what other cases might be important, how those test cases were chosen, or explain the logic used to generate that output. For that you need documentation- either in code or out of code. Automatic tests have their place, but they are not equal to design or documentation. Any place that uses them as such is producing shitty software which will bite them on the ass when the original devs leave.

It sounds like the agile developrs you have run into aren't doing thier jobs particularly well, or perhaps not understanding thier systems very well... Automated tests tell you exactly what is there, nothing more. It tells you, as you said, for inputs X, Y and Z you get outputs A, B, and C. However, if they are doing thier tests correctly, then they are basing those tests directly off of user/customer requirements, so what more do you need? If a custormer needs somethng that produces X, then proving that the method/class/system produces X, then it doesn't matter how it arrived at that position. The test doesn't tell you "why", but what use is this information?

All the documentation in the world can do is tell you, at a particular place in time, what somebody wishes would exist, or thinks does exist. Documentation can absolutly NOT tell you "why that output was generated, why that case was important, what other cases might be important, how those test cases were chosen, or explain the logic used to generate that output". It can tell you what somone assumes or knows at the point that it is written, but who knows about NOW? Assumptions change, reasoning changes, algorithms are refined, thrown out, and completely rewritten from scratch every day. In order to learn the "truth" of the matter that you have to go back into the code itself, to the developers, to the customers.

If you just trust the documentation you will be in a FAR more dangerous position that someone who is forced, by agile methods, to go back, constantly, to the source of the information and get the real, up-to-the minute details.

The problem, I guess, is trying to describe agile methods to a culture that simply is not prepared to change enough to accept them. Agile development is a complete restucturing of information flow, it's systemic, not just another guidebooks for the programmers to follow. If it's not being reflected in the entire organization from the coders themselves, to the sales department, to the marketroids, to the top brass, then it will quickly be "proven" a house of cards and you'll be very unimpressed with the results. It's a great system, but not one to implement half-heartedly.

Re:Are you serious? (1)

AuMatar (183847) | more than 8 years ago | (#14430758)

Documentation can absolutly NOT tell you "why that output was generated, why that case was important, what other cases might be important, how those test cases were chosen, or explain the logic used to generate that output".


No, thats ABSOLUTELY what documentation tells you. It tells you what a function is for, and what the expected output is. Your test cases should be documented as well, wether they be automatic or not- why was this test case chosen (corner case? random pick? check some bug we just fixed and want to watch out for in the future?). If your documentation is NOT telling you this, you and your team fail.

Assumptions change, reasoning changes, algorithms are refined, thrown out, and completely rewritten from scratch every day.


And when this happens, the FIRST thing you do is change the documentation to reflect that. If you don't, you aren't doing your job.


If you just trust the documentation you will be in a FAR more dangerous position that someone who is forced, by agile methods, to go back, constantly, to the source of the information and get the real, up-to-the minute details.


If you work someplace that is so sloppy you get into the positions you claim, maybe. But if your workplace is that sloppy, agile methods will be even worse-if you have devs who are so incompetent that they can't update plain text, I shudder to think of what their code looks like.

Unit tests are not design. They are not documentation. They can help a well designed and documented program by finding bugs early, and thus are a good thing. But if you make me pick one to drop, it'd be the unit tests in an instant.

Re:Are you serious? (1)

Randolpho (628485) | more than 8 years ago | (#14430042)

Automated tests do not grant context. Only non-structured narrative documentation can fully explain the purpose and use of a block of code.

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14430227)

Automated tests do not grant context. Only non-structured narrative documentation can fully explain the purpose and use of a block of code.

Do you want your code to me modular and reusable? If so, what good is context?

Re:Are you serious? (1)

Mr. Slippery (47854) | more than 8 years ago | (#14429596)

If you don't know how to refactor, and how to reduce your bloated thousand-line long methods into a series of simple to understand 10-line long methods, you still have much to learn about good code.

If you think that the sole, or even primary, measure of how simple to understand a module is, is the length of the functions or methods, then you still have much to learn about good code.

(For example, I've sometimes found myself refactoring code from a bunch of sort, tightly-coupled routines into one single one to create better encapsultion.)

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14429718)

For example, I've sometimes found myself refactoring code from a bunch of sort, tightly-coupled routines into one single one to create better encapsultion.

Good job! Excellent first step. But are you finished? I'm sure you could find a way to reduce that complexity even further if you spent more time one in.

In my experience, code is very fluid. It can grow and shrink over time, and almost exclusivly, the smaller it becomes, the more readable it becomes... And the more REUSABLE it becomes! The more you reuse code, the fewer overall bugs you will have, the easier it is to continue coding, and the better your code gets.

Re:Are you serious? (1)

Mr. Slippery (47854) | more than 8 years ago | (#14430314)

Excellent first step. But are you finished? I'm sure you could find a way to reduce that complexity even further if you spent more time one in.

Of course there was more. I think I ended up shrinking the entire code base on that project by at least ten percent. It was pretty "object-obfuscated" when I got ahold of it, I cleaned up the class hierarchy, factored out some common code, et cetera.

But the issue is the statement that a bunch of short routines are more easily understood than one long one. If you have to jump around six different subroutines to see how some functionality is implemented, that's not necessarily easier to understand than one larger routine.

A routine should be as long as it needs to be to accomplish its function; sometimes that means 1,000 lines nicely encapsulated in one "box" of a routine, rather than a bunch of little boxes tied together.

Re:Are you serious? (1)

gnovos (447128) | more than 8 years ago | (#14430394)

of course, all of this only really applies to junior developers. If you stick with the rule "simpler, shorter is better" you can almost never go wrong. Once you find out where you can go wrong, you may not need that rule any more.

Re:Are you serious? (1)

BobNET (119675) | more than 8 years ago | (#14430719)

Good luck in figuring out what the uncommented code does after the programmer is gone, then...

Re:Are you serious? (1)

Grab (126025) | more than 8 years ago | (#14428991)

No such code exists. There are *portions* of code that don't need comments, but the code in general *will*.

Grab.

Re:Are you serious? (1)

Metasquares (555685) | more than 8 years ago | (#14429644)

You aren't commenting your code (else you'd see a lot of "c++; //increment c" stuff); you're commenting your logic.

Maybe the code is self-documenting, but program logic for any reasonably complex problem is not. I don't care how much you've abstracted it; you still need to show how you're using those abstract pieces to solve the problem you're given. You still need comments.

If the developers refuse to comment their code on this basis, I'd probably get someone of average intelligence from sales or HR to read it and explain what it does. If he can't do so, the developer either starts commenting or looks for a new job.

Re:Are you serious? (1)

AuMatar (183847) | more than 8 years ago | (#14429915)

There's no such thing as code which is so clear it does not need comments. If there's a developer who thinks his is, he needs to have his head removed from his ass.

Re:Are you serious? (1)

blincoln (592401) | more than 8 years ago | (#14429476)

If your code is not commented it's not complete. My advice is to fire every developer that doesn't think that comments are necessary.

Seriously.

I code C# for fun, on my own. I still comment, because otherwise when I go to look at it in a year or two, I will have forgotten the reasoning behind some of my decisions.

I do a bit of it at work too. I'm an engineer there, but a few people in my group use ASP, ASP.NET, and VB.NET to write simple utility apps. Trying to work with their code is a *nightmare* because there are few if any comments. There's just too many different ways to write program logic for it to be guaranteed that the next person who comes along will be able to quickly figure it out just because they know the language.

I'm not bad at reverse-engineering. I taught myself basic MIPS assembly so I could hack the PS2 versions of the Legacy of Kain games. It's certainly *possible* for me to eventually figure out someone else's code, no matter how badly-written it was, but if they had commented it I wouldn't waste time on understanding instead of changing.

If anyone is thinking "dude, you're just an engineer, developers write better code," you're wrong. I've looked at the source code for our internally-developed apps a few times, and it was frequently as bad. Allegedly since those apps were written, the development groups have started requiring comments - with exceptions for things like "//increment i" and "//iterate through the recordset" kind of stuff.

Here's a comment... (1)

HaydnH (877214) | more than 8 years ago | (#14428146)

If I haven't touched a project for 6 months it can take me a little while to get to grips with my own code if I haven't commented it properly - then again perhaps I just drink too much!

I don't think a standardized way of commenting is necessary though, as long as there is sufficient comments for a new team member (or a forgetful author like me) to understand the code in a reasonable time.

Haydn.

Re:Here's a comment... (0)

Anonymous Coward | more than 8 years ago | (#14428442)

Sorry to nitpick, but fix your sig boi!

Douglas Adams, not Admas

Use module/function comments (3, Insightful)

V. Mole (9567) | more than 8 years ago | (#14428230)

Comments won't protect you against bad programmers; they'll write bad/confusing code and comments no matter what.

However, I've found that writing semi-structured comments for each module and function (or object/method, if that's your poison) using something like doxygen is worthwhile for ongoing maintenance. It helps others see what the intent is, and provides a basis for writing unit tests. It even helps the original coder when they come back to the module 6 months later. It's not a matter of whether it's public code, just basic internal docs.

just write code that works (1, Informative)

jim_redwagon (845837) | more than 8 years ago | (#14428271)

I think the hardest thing about forcing standards is that they get in the way of actually writing workable code.

If I have to sit there and worry if I have added enough comments so Joe Firstjob can understand what I am doing, the project is going to be late and chances are I'll lost that train of thought that I was following to get through that function.

My usual mode of 'documentation' use real language function returnUserShoppingCart and variable shopperLastPurchaseDate names and add comments noting loop/if-then statments and anything I know I will need a refresher on. I also use comments to state why I did something that way, ie: business rule in effect as of this date, etc.

Your best bet is to know your staff/fellow programmers, learn their styles (or at least become aware of them enough to follow along) and make sure you have checkpoint/target status deadlines. The last to make sure you don't have someone writing 'hola world' for 5 months.

Re:just write code that works (1)

Ithika (703697) | more than 8 years ago | (#14429256)

You've just been re-reading the Brilliant Paula Bean [thedailywtf.com] haven't you? :)

Sometimes you just gotta wonder whether the IT industry (if such a thing can be said to exist) has any pride in its work at all. I think I'll just stick to the outskirts and reading the horror stories!

Retrofitting comments is admittedly a pain... (0)

Anonymous Coward | more than 8 years ago | (#14428287)

But if "no comments" is an option, you must work on REALLY small projects.
I've gotten to the point where I comment en evmy throwaways, because I have a
dusty directory full of them and occasionally I pull one out again.

Here's the simple solution that works for me: any time I have to stop and think
about code, either to write it or when (re-) reading it, write those thoughts
down in the form of comments. I have *one line* of code that's particularly
subtle (it's a function approximation), so I broke it out into its own function
and gave it a page (printed page - 60 lines) of comment explaining what it does
and why the approximation is useful.

But I spent a day designing that approximation, so the think time was already spent.
All I had to do was write it down the first time.

Sometimes the comment gets a bit long and rambling if I make multiple
attempts at the solution, but deleting redundant text is pretty easy.

On the other hand, some functions are so obvious as to not need anything, although
I usually try for a one-line overall comment. I at least had to think about
how to break the work into functions and where a good boundary would be.

Doc Generation? (1)

Telastyn (206146) | more than 8 years ago | (#14428301)

Seems like you missed a step. First you decide if you're going to use an auto-generated code documentation tool like Doxygen. That alone will dictate the majority of any comment-standard.

All code should be well documented (3, Insightful)

ArwynH (883499) | more than 8 years ago | (#14428311)

Commenting and documenting code is something all programmers should do. Not doing it is highly unprofessional and should not be allowed in any self-respecting firm. Making sure the documentation/comments are upto date is included in that statement.

On the other hand just because code is well documented that doesn't mean it's easily maintainable. There are various techniques used to generate good maintainable code. But without documentation any code more complex that 'hello world' tends to be a pain to maintain no matter what techniques you use.

I personaly also find the formating of code (and comments) just as important as commenting it. Reading code formated in a way you're not used to can be a pain and reading code formated in different ways doubly so. So a company-wide standard for formating code/comments would be a good idea.

The one problem with comments (4, Insightful)

MarkusQ (450076) | more than 8 years ago | (#14428357)


There is one problem with comments, but it is a show stopper as far as I'm concerned.

Computers never read the comments, while programmers tend to read comments rather than code. The first part is obvious, and the second is easy to demonstrate. Together, they are a recipe for disaster.

Uncommented code has a number of disadvantages, but the overriding (IMHO) advantage is that both the computer and the programmer are dealing with the same thing, the code. On the other hand, with commented code they are dealing with two similar but distinct things, that are related in exactly the same way as a fine-print contract (the code) and the car salesman's verbal promises (the comments). When push comes to shove, the salesman's words mean nothing and the contract is what matters. So why even listen to the salesman?

-- MarkusQ

P.S. This is not to say that I never comment code; only that I do so sparingly and never trust the comments.

The one problem with MDA (0)

Anonymous Coward | more than 8 years ago | (#14428822)

"Computers never read the comments, while programmers tend to read comments rather than code. The first part is obvious, and the second is easy to demonstrate. Together, they are a recipe for disaster."

So what do you think about executable models [wikipedia.org]?

Re:The one problem with MDA (1)

MarkusQ (450076) | more than 8 years ago | (#14428954)


The idea is neat, though such ideas often come with their own problems--specifically, version control and change management, when the models can't be easily treated as flat text.

Another interesting trick I've seen prototyped (but not in use) is code animation; the documentation consists of a collection of sample cases (which double as test cases) and a specification of what to show (and how to show it). To see how the code works, the tool animated the samples using the actually code. IIRC the examples included a sort, a threaded message passing application, and a cryptography (or perhaps it was data compression) routine. The key point again being that the programmer was looking the same thing as the computer.

--MarkusQ

The one problem with MDA-CVS. (0)

Anonymous Coward | more than 8 years ago | (#14429299)

"The idea is neat, though such ideas often come with their own problems--specifically, version control and change management, when the models can't be easily treated as flat text."

Well since for most tools the model is basically an XML file behind-the-scenes. Something like CVS is possible. Just as image-based languages .i.e. Smalltalk can have version control.

There are open-source tools that help one do MDA, like GME [vanderbilt.edu], StarUML [staruml.com], and Openmdx [openmdx.org]. The missing part to all of these is of course TDD (test-driven-development [wikipedia.org]).

Re:The one problem with comments (1)

neelm (691182) | more than 8 years ago | (#14428890)

You point out a good reason for comments... when the comments don't match the code, that's a good sign of where the bug is. When I'm going behind another programmer looking for a bug I've been tasked to fix reading his comments tells me if his logic was wrong, or the code.

I suppose you could get away with some comments in say, a blog site, but if you're working as a developer on a team with more complex requirments, and the origional programmer may not even be with the company anymore, comments are a must.

It's not like it takes that long either...

Re:The one problem with comments (3, Interesting)

Grab (126025) | more than 8 years ago | (#14429024)

You're misunderstanding the real purpose of comments.

If your comment says "Increment i" and the code says "--i" then yes, things are fucked. But the purpose of comments is not to describe *what* the code does but *why* it does it (and occasionally *how* as well if it's not clear, for example if there's some particularly gnarly maths or pointer weirdness involved).

Anyone writing comments saying *what* their code does what it does needs their code reworked at review - and if they're not on their first job then they need firing.

Anyone *not* writing comments saying *why* their code does what it does needs their code reworked at review - and if they're not on their first job then they need firing.

Grab.

I agree, to a point (1)

MarkusQ (450076) | more than 8 years ago | (#14429107)


I agree, to a point. "Why" (and "how") comments are far better than "what" comments, but the fundumental problem still applies. Even "why" comments can obscure bugs:

i -= 1000 if i > 1000 # We only have room for (and only need) three digits
--MarkusQ

Re:I agree, to a point (1)

jackbird (721605) | more than 8 years ago | (#14429388)

How does that obscure the bug in that line? It makes it much more obvious because you know what they're trying to do.

Re:I agree, to a point (1)

MarkusQ (450076) | more than 8 years ago | (#14429737)


How does that obscure the bug in that line? It makes it much more obvious because you know what they're trying to do.

Because (and this has been well tested) people tend to read the comment instead of the code. The high tech tests tracked people's eye movements and such, but you can show the same thing by timing how long it takes people to find bugs, or just quizing them afterwards.

The effect gets more pronounced for larger segments of code. In one example that I recall, half a group of programmers were given a ~10 line binary search routine (with no comments), and asked what it did. The other half were given the same code but with the comments from a shell sort routine ("why"-comments).

When asked what the routine did, the first group was almost always correct, and the second got it wrong more than half the time.

--MarkusQ

Re:I agree, to a point (1)

jackbird (721605) | more than 8 years ago | (#14430393)

But without a comment, there's no way to tell that code is buggy. It could be setting an index in a 1000-element 1-based array.

Re:The one problem with comments (1)

afidel (530433) | more than 8 years ago | (#14429770)

That's where EIFFEL has an advantage over other languages, it's comments can't disagree with the code. The comments are part of the design by contract methodology that the language enforces. You setup your incoming inputs with an expect statement, then guarentee your outputs with an ensure block. Failing to meet either the expect or ensure conditions throws an exception which you can catch and hadle as needed.

Re:The one problem with comments (1)

p3d0 (42270) | more than 8 years ago | (#14430189)

Comments and code should not overlap in their content, so your complaints are irrelevant. If you have code that says "x=0" and a comment that says "set x to zero" then you don't understand what comments are for.

Re:The one problem with comments (2, Insightful)

ianezz (31449) | more than 8 years ago | (#14430377)

On the other hand, with commented code they are dealing with two similar but distinct things

IMHO, the point of comments is not to tell other how things are done, but why they have been done in that specific way. No amount of code can tell you that.

Why Documentation is Absolutely Necessary (3, Insightful)

jgardn (539054) | more than 8 years ago | (#14428528)

In the real world, you work on a project for a time then move on to something else. Then you or someone else is assigned to revisit your old code. You don't have time to relearn the code and you certainly don't have time to sit down the guy called in to fix it and tranfers your understanding of the project. (If you did, you would've documented the code properly in the first place, right?)

When companies don't comment and don't document their code properly, they begin this vicious cycle of rewriting old code because no one know how it should or does work and no one has the time to figure it out. Let me explain why.

Imagine you find a software package on the internet licensed in a way that suits your needs. Now imagine that software package, with very few modifications, will do exactly what you need it to do for you project. You have a choice: (1) Take that software, modify it, and deploy it, or (2) write your own from scratch.

There is only ONE determining factor in whether you inevitably choose (1) or (2), and that is DOCUMENTATION.

Now remember that software you find in your own company is no better or worse than software you find on the internet, only it has a much more liberal license for your purposes. But does that change the fact that in order to make use of it you have to understand it?

On my job, I have an approach to undocumented software. I start writing documentation for it, whether or not the author wants me to and whether or not there is really enough time for it. If I have questions, I find the author, and approach him with pen and paper. We sit down and write documentation together. Inevitably, by documenting what I find in other people's codes it ends up saving me more time than if I wrote the code myself, documented it, and debugged it. So I have been able to finish a great number of projects ahead of schedule because I don't write code: I READ it. (And this is a perl world too!) And in the end, others are able to come and read my documents and notes and reuse the software as well.

Theory vs Practice (2, Insightful)

SmallFurryCreature (593017) | more than 8 years ago | (#14428603)

Commenting and Documenting both take time. Wich you often don't have, so you don't do it or worse do it badly.

If somebody asks you to code something (and you can get away with it) tell them this, "okay that is X hours for just the code and X*3 for the code and proper documentation."

Yes I made the *3 up. You know why? Because I have always had the misfortune on working on the kinds of projects where I either didn't get the time needed or the guy before me didn't do the documentation.

If you want to take a ride in your car you should walk around it making sure it is in proper working order like all the lights working. It is a law and enforced by people with guns. Now how many of you do it?

Okay, nobody. So now you are under time pressure, you are underpayed and overworked and you got a choice, either deliver on time or tell your boss your still writing documentation on the installer.

When I was still young and fresh I thought that following procedures is the way to do it. Boy was I wrong. The secret? Code fast and ugly and make sure you have moved on before the shit hits the fan. Oh and never ever be lumbered with a maintenance project. I never even seen documentation wich was up-to-date.

The entire discussion on wether or not to document is wrong. The discussion should be wether you will allot enough time to non-coding work. It applies to so many things, peer review of code, sharing and re-use of selfmade libraries, layout standards, knowledge sharing, etc etc.

The larger the company the more time can successfully be spend on non-coding things that however are always badly reviewed during your evalutation. Oh yeah very nice you tought everyone else how to code securely and made sure nobody else has bugs in their code. Now how many lines did you write? Oh, no pay rise for you.

So simply ask this of the people in favor of proper documentation. How will they find the time?

And ask the non documentation people if they will do the maintenance on their own projects 10 years in to the future.

My experience? I needly predict I need X to write code and then Y to write the proper documentation. I deliver the code and get the next project and if I protest that I am still working on the documentation then I am told that it can wait. I am still waiting. Oh and the risk of doing it properly? You get lumbered with writing maintenance and writing the documentation for everyone else because your good at it but a slow coder. ARGH!

Just comment the basics, point out in a readme.txt where to start reading and tell them wich bar in the neighbourhood serves hard liquor during lunch. Oh and if you comment some code out come back later and delete it. Can be very confusing if you have to wade through a problem where 2/3's is old code.

Tech Reviews (2, Informative)

crmartin (98227) | more than 8 years ago | (#14428658)

The answer (40 years of experience with this) is not to set a standard on how much commenting is needed; it's to have walk-throughs of the code with an intelligent reader who isn't directly involved with the code. If they can read and understand the code, it's enough.

Look into Fagan reviews [google.com] for details on an effective way to handle this.

Re:Tech Reviews (1, Insightful)

Anonymous Coward | more than 8 years ago | (#14429482)

Agreed. Have a competant engineer give it a lookover.

A few other points:
Don't confuse comments and design documents.

Focus on the "why" -- the code itself is the "how." If something seems nonintuitive, describe why you made that decision. Your goal is to get the reader to the same place in your engineering that allowed you to solve the problem and describe the trade-offs. If you have to leave a "popcorn-trail" of ideas you tried, do so. Spending a week debugging to understand the interactions of a complex system should be done once, then described so that the next person doesn't have to.

Mandatory "flower box" comment blocks at the top of every function are annoying, a waste of time, and a liability. If they exist at the top of every function, then the important comments explaining difficult-to-understand sections get lost in the "noise" of the comments for trivial functions.
Comments are a liability if you work on a regulated or validated system (think pharma, air traffic control, banking, missile guidance, etc. or any other system where life & fortunes are involved) -- failure to update the comments means the system is out of compliance and a simple change or refactoring turns into a huge time-waster as you go about changing dozens of trivial comment blocks to reflect a new layering or ownership structure.

Which brings me to the final point: if a block of code is complex enough to need 1) a comment, and 2) a big comment to explain its inner workings, then you probably should refactor and simplify.

The best thing to do (2, Insightful)

ogar572 (531320) | more than 8 years ago | (#14428685)

is have all the programmers program in the same style and guidelines. Examples include all SQL statements start with $sql_, making sure code is properly indented, variable naming that are easy to recognize, where certain functions should be placed in the directory structure, and the such. Simple things like that should eliminate the need to write a novel for every piece of software that you write.

Mmmm comments (1)

skotte (262100) | more than 8 years ago | (#14428756)

May I be a sort of voice of reason, of a kind? comments are tasty things which should be used regularly and often. spelling and grammar may not be necesarry to be observed, but in my opinion, I would much rather see roughly one comment fFor every, say, 6 lines of code. I dont mean in exact ratios portioned out like rations .. you could have a whole page or two of comments sometimes which covers 3 pages of other stuff, if it's all somehow convenient. that's cool. And, you know, variables and routines with obvious names may not need everything documented .... but somewhere i should be able to get some information about much of what a system does. in my experience, it seems as though once about every sixth line or so, we do something a little subtle which a nice simple comment might help. more is good, yes. you know, and i'm talking like /* add interest, dump to screen */ or /* average RGB values */ or .. that sort of thing. simple verb noun descriptors which tell what's going on. The kinds of things your pseudocode should say -- you do remember seudocode, right? that's the stuff your CIS 101 prof told you you should always use, and you havent touched since?

I mean, I'm inclined to say "if you don't use commenets everywhere you should be shot!" but i dont have that many bullets, and i'm just as inclined to say "you cant make me use comments if i don't wanna!" but i also don't have that many bridges so i'd rather not burn them *all* down.

a nice sane happy medium is a good thing.

simple rule (2, Insightful)

outcast36 (696132) | more than 8 years ago | (#14428824)

Document at the function level (javadoc style is nice). It's easy to remember and it helps you refactor. If you are documenting the internal magic, then the magic could probably be moved out into it's own function, which then gets it's own documentation. voila.

If you need a documentation/commenting consultant, I am available to guide your team through this process.

Comments are compromise (1)

gnovos (447128) | more than 8 years ago | (#14428942)

Basically, treat comments like you should credit card debt. Use it rarely, only when you really have to, and try to get rid of it as soon as possible. If you can write the code in a clearer way, one that does not need comments, then do so, ASAP.

In a perfect world, the ONLY thing that you want to have comments are APIs into closed code (some outward-facing API that you aren't willing to give the source to). Everything else should only have comments when the code is too complex to be understood by reading it... and that code should be first in line for refactoring.

And never NEVER write comments like "the doFoo(Stringx, String y) does foo by taking string x and string y as parameters". This is useless, clutters up everything, and makes the important comments less visible.

if code is hard to write... (1)

acomj (20611) | more than 8 years ago | (#14428960)

It SHOULD be hard to understand.

http://thc.org/root/phun/unmaintain.html [thc.org]

In all seriousness. I would just enforce "header" comments to a particular style (javadoc..etc). The rest is up to the individual programmer.

The trouble as pointed out earlier is that programmers/code reveiwer have to be always be updating comments as the code gets updated. This doesn't always happen and is the caused me personally some problems as I took the comment to be right, when clearly they were not. I use comments as a guide now.

Please help me on this (2, Interesting)

bill_kress (99356) | more than 8 years ago | (#14428967)

I keep seeing all these arguments either against commenting or against verbose languages because, supposedly, they slow development.

Now, Maybe I've just been programming too long and have gotten too good at it, but typing is never ever a slow-point in coding; heck, even learning a new language doesn't slow you down too much!

The slow part is designing your code correctly so that it's fully factored and as bug-free as you can manage--this takes thought and a bit of time, but no where near as much time as it would take to do the same release with cut & paste (I've seen it many times).

So I'm trying to figure this out, why are people making these arguments? Is it that for unexperienced people it truly is harder to put comments in with your code? Maybe they don't know how they did their magic and don't want others to figure them out? Maybe they never took a typing class and it truly takes more time to code than think? I'm really at a loss here.

Oh, and as for the authors question, you have a FANTASTIC opportunity to improve your company tenfold. Take notes of those arguing against commenting. As soon as you've collected all the votes, throw them away and FIRE anyone who was against documentation--they should not be working in any company, at least not as a programmer! If you hired people who understood programming and the development cycle, that question would have never come up.

the reason for comments (1)

CDS (143158) | more than 8 years ago | (#14429022)

The problem isn't "should we comment" or even "how many comments should there be" -- the problem is actually "what should the comments say" at my work I have seen several different styles of comments and invariably, one type of comment stands out as useful and other comments are mere distractions, at best. Comments should never be used to document how code works. The code itself shows how it works -- or at least it SHOULD. If your code isn't readable, THEN RE-CODE IT! It's not maintanable. I don't care how you were able to make 18 things occur in one line of code. that's not elegant. that's dumb. It's not maintainable. Rewrite it so it's clear. Comments should document WHY the code is written that way. I don't care that:
while(i<10) { /* repeat until i is greater than 10 */
That's useless. that just takes up space. and what happens if you change it to
while(i<20)
? then your comment is out of date. However,
while(i<10) { /* spin through the list, searching for blah */
tells me the purpose of this while() statement, and tells me something about the body of the loop as well. Even better would be a block comment above it, of course (describing the entire body of the loop, for example) What I do is I write the comments FIRST -- I lay out the high-level design of the program in the comment block, then go and add the code in the appropriate place within the comments. That way my design is documented and my code is created from the design. That ensures the comments are correct, at least initially. The other thing do is document changes within the comments:
while(i<20) { /* Spin through the list, searching for blah */ /*@01C*/
then in the prolog of my program, I have a comment that describes changeflag 01, who made the change, the date of the change, and the location of the document describing the need for the change (bugzilla number, etc). This not only keeps the documentation up to date, but provides a paper trail. If someone else looks at the code and doesn't understand why we stop at 20, they can just look up that changeflag and come find me to talk about it.

documentation?? what's that? (2, Funny)

keithhackworth (902524) | more than 8 years ago | (#14429223)

I've been programing for most of my life and have only documented about 3 peices of my work where things got so complex, it was making my head hurt. Even then, my comment says "I feel sorry for the next person who has to figure this out..." or "Don't ask what I was thinking here...".

IMO, if someone comes up and asks for documentation, they need to be fired! They obviously either 1) don't know how to read code and shouldn't be programming; 2) Don't understand the problem the code is trying to solve.

Code is like a foreign language - you either know it or you don't. Comments are for people who don't know it; and if they don't know it, they need to find another job or learn the language.

When I program, I get in this "state" where I can't stop. When I get to that state, I am a VERY FAST programmer. If I were to document my coding, it would take me 5 times as long to write it because I would never get in that "state". On the rare occassion that I look at code and can't figure it out, I rewrite it because, obviously, the code sucks. To keep my code from sucking, I have very strict guidlines that I use when programming (in order of importance):

1. MOST IMPORTANT - use tabs in routines to show where routines start and stop
2. use tabs in routines to show where routines start and stop
3. If I do comment (yea right), Don't put parenthesis, squiglys, or brackets in the comments - it screws up vi's % command.
4. use tabs in routines to show where routines start and stop
5. Make variables' and functions' names intutive.
6. use tabs in routines to show where routines start and stop
and last, use tabs in routines to show where routines start and stop


If you use these rules and have a decent progrmamer, there's probably very little need for comments.

Keith

Re:documentation?? what's that? (1)

ObsessiveMathsFreak (773371) | more than 8 years ago | (#14429332)

IMO, if someone comes up and asks for documentation, they need to be fired! They obviously either 1) don't know how to read code and shouldn't be programming; 2) Don't understand the problem the code is trying to solve.

On the rare occassion that I look at code and can't figure it out, I rewrite it because, obviously, the code sucks.


Hack Mplayer. Then come back to me.

Document your code or hit the road (2, Insightful)

Mr. Slippery (47854) | more than 8 years ago | (#14429345)

that comments are not necessary for clarity and can be dangerous if not kept up to date

If you can't keep comments up to date in the code you're responsbile for, you're not competent to be responsbile for the code.

There shouldn't be any debate on the need for documentation. Document your code or hit the road. The only issue is where it goes, in separate docs or in comment blocks. (Doxygen and similar systems make it easy to generate separate docs from comment blocks. Recommended.)

Code reviews are the best enforcement - if you go in and everyone's asking "what the hell does this block do???", you need to comment it.

you are not invincible (0)

Anonymous Coward | more than 8 years ago | (#14429626)

i work in a small shop where one of our programmers had a massive stroke the week before christmas.

as a non-"official" programmer, picking up the slack would have been a LOT easier if his code were commented.

Like a math proof (4, Insightful)

Metasquares (555685) | more than 8 years ago | (#14429687)

Code, like a math proof, is written in a specialized language that people outside of the field are unlikely to understand well.

Try removing all text from a sufficiently complex math proof, leaving only the mathematical notation, and see if you can still figure out what the mathematician is doing.

Now try to publish a paper like that.

No matter how amazing your results, such a proof will not be accepted by the mathematical community. I've run across some very good papers that were discarded because no one, including the author, could understand what all that math was supposed to *do* anymore.

You should be writing code the same way as you'd write a good proof. You don't need to explain why 1+1=2, but you definitely do not want to skip over critical parts of a proof that are necessary to understand before reaching the conclusion.

What I said earlier (2, Informative)

arensb (17851) | more than 8 years ago | (#14430064)

I wrote what I thought was a pretty decent article on comments a while back:
http://freshmeat.net/articles/view/238/ [freshmeat.net]

The gist of it is that the source tells you what the code does, and comments tell you what it's supposed to do, why it looks that way, how it connects to other parts of the program, any weird gotchas, and so forth.

Comments help you zero in on the part of the code you're looking for when you're trying to fix a bug; and they help confirm that the code really does what you think it does.
Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...