What is self-documenting code and can it replace well documented code?

Question

I have a colleague who insists that his code doesn't need comments, it's "self documenting."

I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

• What is self documenting code
• Can it really replace well commented and documented code
• Are there situations where it's better than well documented and commented code
• Are there examples where code cannot possibly be self-documenting without comments

Maybe it's just my own limitations, but I don't see how it can be a good practice.

This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer. I believe I need to more fully understand his perspective to convince him otherwise. Start a new question if you must, but don't argue here.

Also, those of you who are arguing against self documenting code -this is primarily to help me understand the perspective (ie, positive aspects) of self-documenting code evangelists.

Answer 1

Well, since this is about comments and code, let's look at some actual code. Compare this typical code:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

To this self-documenting code, which shows what is being done:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

And then to this documented code, which better explains why it is being done:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

And the final version of code as documentation with zero comments needed:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Here's an example of a poor commenting style:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

In the last example, comments are used when variables should have been descriptively named instead, and the results of an operation are summarized when we can clearly see what the operation is. I would prefer the self-documented second example to this any day, and perhaps that is what your friend is talking about when he says self-documented code.

I would say that it depends on the context of what you are doing. To me, the self-documented code is probably sufficient in this case, but a comment detailing the methodology behind what is behind done (in this example, the equation) is also useful.

Answer 2

In my opinion, any code should be self-documenting. In good, self-documented code, you don't have to explain every single line because every identifier (variable, method, class) has a clear semantic name. Having more comments than necessary actually makes it harder (!) to read the code, so if your colleague

• writes documentation comments (Doxygen, JavaDoc, XML comments etc.) for every class, member, type and method AND
• clearly comments any parts of the code that are not self-documenting AND
• writes a comment for each block of code that explains the intent, or what the code does on a higher abstraction level (i.e. find all files larger than 10 MB instead of loop through all files in a directory, test if file size is larger than 10 MB, yield return if true)

his code and documentation is fine, in my opinion. Note that self-documented code does not mean that there should be no comments, but only that there should be no unnecessary comments. The thing is, however, that by reading the code (including comments and documentation comments) should yield an immediate understanding of what the code does and why. If the "self-documenting" code takes longer to understand than commented code, it is not really self-documenting.

Answer 3

The code itself is always going to be the most up-to-date explanation of what your code does, but in my opinion it's very hard for it to explain intent, which is the most vital aspect of comments. If it's written properly, we already know what the code does, we just need to know why on earth it does it!

Answer 4

Someone once said

1) Only write comments for code that's hard to understand.
2) Try not to write code that's hard to understand.

Answer 5

The idea behind "self-documenting" code is that the actual program logic in the code is trivially clear enough to explain to anyone reading the code not only what the code is doing but why it is doing it.

In my opinion, the idea of true self-documenting code is a myth. The code can tell you the logic behind what is happening, but it can't explain why it is being done a certain way, particularly if there is more than one way to solve a problem. For that reason alone it can never replace well commented code.

Answer 6

I think it's relevant to question whether a particular line of code is self-documenting, but in the end if you do not understand the structure and function of a slice of code then most of the time comments are not going to help. Take, for example, amdfan's slice of "correctly-commented" code:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

This code is fine, but the following is equally informative in most modern software systems, and explicitly recognizes that using a Newtonian calculation is a choice which may be altered should some other physical paradigm be more appropriate:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

In my own personal experience, there are very few "normal" coding situations where you absolutely need comments. How often do you end up rolling your own algorithm, for example? Basically everything else is a matter of structuring your system so that a coder can comprehend the structures in use and the choices which drove the system to use those particular structures.

Answer 7

I forget where I got this from, but:

Every comment in a program is like an apology to the reader. "I'm sorry that my code is so opaque that you can't understand it by looking at it". We just have to accept that we are not perfect but strive to be perfect and go right on apologizing when we need to.

Answer 8

First of all, it's good to hear that your colleague's code is in fact clearer than other code you have seen. It means that he's probably not using "self-documenting" as an excuse for being too lazy to comment his code.

Self-documenting code is code that does not require free-text comments for an informed reader to understand what it is doing. For example, this piece of code is self-documenting:

print "Hello, World!"

and so is this:

factorial n = product [1..n]

and so is this:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Now, this idea of an "informed reader" is very subjective and situational. If you or anyone else is having trouble following your colleague's code, then he'd do well to re-evaluate his idea of an informed reader. Some level of familiarity with the language and libraries being used must be assumed in order to call code self-documenting.

The best argument I have seen for writing "self-documenting code" is that it avoids the problem of free-text commentary not agreeing with the code as it is written. The best criticism is that while code can describe what and how it is doing by itself, it cannot explain why something is being done a certain way.

Answer 9

Self-documenting code is a good example of "DRY" (Don't Repeat Yourself). Don't duplicate information in comments which is, or can be, in the code itself.

Rather than explain what a variable is used for, rename the variable.

Rather than explain what a short snippet of code does, extract it into a method and give it a descriptive name (perhaps a shortened version of your comment text).

Rather than explain what a complicated test does, extract that into a method too and give it a good name.

Etc.

After this you end up with code that doesn't require as much explanation, it explains itself, so you should delete the comments which merely repeat information in the code.

This doesn't mean you have no comments at all, there is some information you can't put into the code such as information about intent (the "why"). In the ideal case the code and the comments complement each other, each adding unique explanatory value without duplicating the information in the other.

Answer 10

self-documenting code is a good practice and if done properly can easily convey the meaning of the code without reading too many comments. especially in situations where the domain is well understood by everyone in the team.

Having said that, comments can be very helpful for new comers or for testers or to generate documentation/help files.

self-documenting code + necessary comments will go a long way towards helping people across teams.

Answer 11

In order:

• Self-documenting code is code that clearly expresses its intent to the reader.
• Not entirely. Comments are always helpful for commentary on why a particular strategy was chosen. However, comments which explain what a section of code is doing are indicative of code that is insufficiently self-documenting and could use some refactoring..
• Comments lie and become out of date. Code always tells is more likely to tell the truth.
• I've never seen a case where the what of code couldn't be made sufficiently clear without comments; however, like I said earlier, it is sometimes necessary/helpful to include commentary on the why.

It's important to note, however, that truly self-documenting code takes a lot of self- and team-discipline. You have to learn to program more declaratively, and you have to be very humble and avoid "clever" code in favor of code that is so obvious that it seems like anyone could have written it.

Answer 12

When you read a "self-documenting code", you see what it is doing, but you cannot always guess why it is doing in that particular way.

There are tons of non-programming constraints like business logic, security, user demands etc.

When you do maintenance, those backgorund information become very important.

Just my pinch of salt...

Answer 13

The difference is between "what" and "how".

• You should document "what" a routine does.
• You should not document "how" it does it, unless special cases (e.g. refer to a specific algorithm paper). That should be self-documented.

Answer 14

For one, consider the following snippet:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

In this example you have 5 lines of comments per 3 lines of code. Even worse - the comments do not add anything which you can't see by reading the code. If you have 10 methods like this, you can get 'comment blindness' and not notice the one method that deviates from the pattern.

If course, a better version would have been:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Still, for trivial code I prefer not having comments. The intent and the overall organization is better explained in a separate document outside of the code.

Answer 15

In a company where I worked one of the programmers had the following stuck to the top of her monitor.

"Document your code like the person who maintains it is a homocidal maniac who knows where you live."

Answer 16

self-documenting code normally uses variable names that match exactly what the code is doing so that it is easy to understand what is going on

However, such "self-documenting code" will never replace comments. Sometimes code is just too complex and self-documenting code is not enough, especially in the way of maintainability.

I once had a professor who was a firm believer in this theory In fact the best thing I ever remember him saying is "Comments are for sissies"
It took all of us by surprise at first but it makes sense.
However, the situation is that even though you may be able to understand what is going on in the code but someone who is less experienced that you may come behind you and not understand what is going on. This is when comments become important. I know many times that we do not believe they are important but there are very few cases where comments are unnecessary.

Answer 17

One thing that you may wish to point out to your colleague is that no matter how self-documenting his code is, if other alternate approaches were considered and discarded that information will get lost unless he comments the code with that information. Sometimes it's just as important to know that an alternative was considered and why it was decided against and code comments are most likely to survive over time.

Answer 18

I'm surprised that nobody has brought about "Literate Programming", a technique developed in 1981 by Donald E. Knuth of TeX and "The Art of Computer Programming" fame.

The premise is simple: since the code has to be understood by a human and comments are simply thrown away by the compiler, why not give everyone the thing they need - a full textual description of the intent of the code, unfettered by programming language requirements, for the human reader and pure code for the compiler.

Literate Programming tools do this by giving you special markup for a document that tells the tools what part should be source and what is text. The program later rips the source code parts out of the document and assembles a code file.

I found an example on the web of it: http://moonflare.com/code/select/select.nw or the HTML version http://moonflare.com/code/select/select.html

If you can find Knuth's book on it in a library (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.) you should read it.

That's self-documenting code, complete with reasoning and all. Even makes a nice document, Everything else is just well written comments :-)

Answer 19

I would like to offer one more perspective to the many valid answers:

What is source code? What is a programming language?

The machines don't need source code. They're happy running assembly. Programming languages are for our benefit. We don't want to write assembly. We need to understand what we are writing. Programming is about writing code.

Should you be able to read what you write?

Source code is not written in human language. It has been tried (for example FORTRAN) but it isn't completely successful.

Source code can't have ambiguity. That's why we have to put more structure in it than we do with text. Text only works with context, which we take for granted when we use text. Context in source code is always explisit. Think "using" in C#.

Most programming languages have redundancy so that the compiler can catch us when we aren't coherent. Other languages use more inference and try to eliminate that redundancy.

Type names, method names and variable names are not needed by the computers. They are used by us for referencing. The compiler doesn't understand semantics, that's for us to use.

Programming languages are a linguistic bridge between man and machine. It has to be writable for us and readable for them. Secondary demands are that it should be readable to us. If we are good at semantics where allowed and good at structuring the code, source code should be easy to read even for us. The best code doesn't need comments.

But complexity lurks in every project, you always have to decide where to put the complexity, and which camels to swallow. Those are the places to use comments.

Answer 20

I think that self-documenting code is a good replacement for commenting. If you require comments to explain how or why code is the way it is, then you have a function or variable names that should be modified to be more explanatory. It can be down to the coder as to whether he will make up the shortfall with a comment or renaming some variables and functions and refactoring code though.

It can't really replace your documentation though, because documentation is what you give to others to explain how to use your system, rather than how it does things.

Edit: I (and probably everyone else) should probably have the provision that a Digital Signal Processing (DSP) app should be very well commented. That's mainly because DSP apps are essentially 2 for loops fed with arrays of values and adds/multiplies/etc said values... to change the program you change the values in one of the arrays... needs a couple of comments to say what you are doing in that case ;)

Answer 21

Self documenting code is an easy opt out of the problem, that over time code, comment and documentation diverge. And it is a disciplining factor to write clear code (if you are that strict on yourself).

For me, these are the rules I try to follow:

• Code should be as easy and clear to read as possible.
• Comments should give reasons for design decisions I took, like: why do I use this algorithm, or limitations the code has, like: does not work when ... (this should be handled in a contract/assertion in the code) (usually within the function/procedure).
• Documentation should list usage (calling converntions), side effects, possible return values. It can be extracted from code using tools like jDoc or xmlDoc. It therefore usually is outside the function/procedure, but close to the code it describes.

This means that all three means of documenting code live close together and therefore are more likely to be changed when the code changes, but do not overlap in what they express.

Answer 22

The real problem with the so-called self-documenting code is that it conveys what it actually does. While some comments may help someone understand the code better (e.g., algorithms steps, etc.) it is to a degree redundant and I doubt you would convince your peer.

However, what is really important in documentation is the stuff that is not directly evident from the code: underlying intent, assumptions, impacts, limitations, etc.

Being able to determine that a code does X from a quick glance is way easier than being able to determine that a code does not do Y. He has to document Y...

You could show him an example of a code that looks well, is obvious, but doesn't actually cover all the bases of the input, for example, and see if he finds it.

Answer 23

When writing mathematical code, I have sometimes found it useful to write long, essay-like comments, explaining the math, the notational conventions the code uses, and how it all fits together. We're talking hundreds of lines of documentation, here.

I try to make my code as self-documenting as possible, but when I come back to work on it after a few months, I really do need to read the explanation to keep from making a hash out of it.

Now, of course this kind of extreme measure isn't necessary for most cases. I think the moral of the story is: different code requires different amounts of documentation. Some code can be written so clearly that it doesn't need comments -- so write it that clearly and don't use comments there!

But lots of code does need comments to make sense, so write it as clearly as possible and then use as many comments as it needs...

Answer 24

I would argue - as many of you do - that to be truly self documenting, code needs to show some form of intent. But I'm surprised nobody mentioned BDD yet - Behavior Driven Development. Part of the idea is that you have automated tests (code) explaining the intent of your code, which is so difficult to make obvious otherwise.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

Answer 25

A couple of reasons why extra comments in addition to the code might be clearer:

• The code you're looking at was generated automatically, and hence any edits to the code might be clobbered the next time the project is compiled
• A less-than-straightforward implementation was traded off for a performance gain (unrolling a loop, creating a lookup table for an expensive calculation, etc.)

Answer 26

Its going to be all in what the team values in its documentation. I would suggest that documenting why/intent instead of how is important and this isn't always captured in self documenting code. get/set no these are obvious - but calculation, retrieval etc something of the why should be expressed.

Also be aware of difference in your team if you are comming from different nationalities. Differences in diction can creap into the naming of methods:

BisectionSearch

BinarySearch

BinaryChop

These three methods contributed from developers trained on 3 different continents do the same thing. Only by reading the comments that described the algorithm were we able to identify the duplication in our library.

Answer 27

For me reading code that needs comments is like reading text in the language I do not know. I see statement and I do not understand what it does or why - and I have to look at comments. I read a phrase and I need to look in dictionary to understand what it means.

It is usually easy to write code that self-documents what it does. To tell you why it does so comments are more suitable, but even here code can be better. If you understand your system on every level of abstraction, you should try organizing you code like

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Where method name reflects your intent and method body explains how you achieve your goal. You anyway can not tell entire book in its title, so main abstractions of your system still have to be documented, as well as complex algorithms, non-trivial method contracts and artifacts.

If the code that your colleague produc is really self-documented - lucky you and him. If you think that your colleagues code needs comments - it needs. Just open the most non-trivial place in it, read it once and see if you understood everything or not. If the code is self-documented - then you should. If not - ask your colleague a question about it, after he gives you an answer ask why that answer was not documented in comments or code beforehand. He can claim that code is self-document for such smart person as him, but he anyway has to respect other team members - if your tasks require understanding of his code and his code does not explain to you everything you need to understand - it needs comments.

Answer 28

Most documentation / comments serve towards assisting future code enhancers / developers hence making the code maintainable. More often than not we would end up coming back to our module at a later time to add new features or optimize. At that time it would be easier to understand the code by simply reading the comments than step through numerous breakpoints. Besides i would rather spend time thinking for new logic than deciphering the existing.

Answer 29

Good design structure helps to point out that some functions are for general use and some for random business logic even though you don't have a comment saying "this function is general".

We should not forget about design and specification documentation though. Those have or at least should have much of the texts that are not necessarily needed in comments. Software often have also user manuals and other description documents, and those should be in sync with what the program does. The situation is not great if the user has to find out what the software does from the source code instead of a manual. So self documenting code still doesn't mean that the actual software has been documented.

Think about traceability of features, too. When you have your manual, then you should be able to trace the features to source code and back for better maintainability. Manuals and specifications are not that much about programming, but they are about software engineering. The bigger the software, the more engineering is needed.

Answer 30

I think what he might be getting at is that if comments explain what the code is doing it should be re-written to be clear what it's intent is. That's what he means by self documenting code. Often this can mean simply breaking up long function into logical smaller pieces with a descriptive function name.

That doesn't mean the code should not be commented. It means that comments should provide a reason why the code is written the way it is.

Answer 31

I believe that you should always strive to achieve self-documenting code because it does make it easier to read code. However, you have also got to be pragmatic about things.

For example, I usually add a comment to every class member (I use documentation comments for this). This describes what the member is supposed to do but not how it does it. I find that when I am reading through code, particularly old code, this helps me remember quickly what the member is for and I also find it easier than reading the code and working it out, particularly if the flow of code jumps around quite a bit.

This is just my opinion. I know of plenty of people who work without comments at all and say that they find this to be no problem. I have, however, asked somebody about a method they wrote six months previous and they have had to think for a few minutes to tell me exactly what it did. This isn't a problem if the method is commented.

Finally, you have to remember that comments are equally part of the system as code. As you refactor and change functionality you must also update your comments. This is one argument against using comments at all as they are worse than useless if they are incorrect.

Answer 32

I think its a matter of the right amount of documentation, rather than all or none. If the parameters to a function are well named, you often don't have to say exactly what they are, e.g. char *CustomerName is pretty obvious. If you use assert value ranges for parameters, you don't have to document those ranges as well. IMO, documentation should cover everything which is less than obvious and hence needs some explanation, and most code needs some documentation. Personally, I'd rather see an illustrative example of how a given function works than descriptive documentation, in most cases.

Documentation for documentations sake can be a waste of time, as the documentation needs maintenance to be kept up to date with the code base. If no one will benefit from reading it, don't produce it.

Answer 33

I'd turn this around.

Ask yourself what you don't understand in his code and then ask him to document those. And maybe you could also tell us some.

Answer 34

Here are my best answers to your questions.

Self documenting code is code that's written clearly with class, method, function, and variable names that make it's intent and function easily understood. If done well, it is the documentation.

It can replace code that's well commented and documented, but I've rarely seen it. Too many times, programmers believe that they are good enough to do this, but the best way to knock them down is to start asking questions. If they have to start explaining too much, then their code wasn't clear enough. You shouldn't have to read the code to know what it does.

There may be some situations where it's better. If the code is small and simple, then you may clutter things up by adding documentation.

Code that includes an algorithm should contain comments. Most times, even the original programmers can't remember what the heck they were thinking a few months ago when they wrote a long function.

Answer 35

This is an excellent question. It traces back to the first programming language that allowed comments, I'm sure. The code certainly should be as self-documenting as possible. Comments that point out the obvious, should be eliminated. Comments that make it easier to understand the intent, purpose, and use of a given method or section of code can be invaluable to those of us dolts that may be less familiar with the language or code in question. Structured comments that allow for the generation of API documentation are a good example. Just don't comment an IF statement that checks to see if a checkbox is checked and tell me that you're checking to see if the checkbox is checked. Restating the obvious in a comment is the worst waste keystrokes in our universe.

//For example, the above text deals with what is a useful comment

Answer 36

Self documenting code is code that is trivially easy to understand. Variable naming goes a long way to making code self documenting, but i find the best tactic is to break any complicated logic down into tiny little chunks and refactor that information into seperate methods with verbose and informative names. Then your complicated methods become simply a list of steps to be performed. The tiny private helper methods then are documented sufficiently by their own method name and the complicated methods are documented as a sequence of abstract steps to be performed. In practice this strategy cannot always be applied perfectly so comments are still very useful. Plus you should never completely abandon any tool which will help you write code that is easier to understand.

Answer 37

If your code isn't completely clear without comments, then there's room to improve your code.

I'm not saying "don't comment unclear code". I'm saying "make your code clear".

If you end up leaving your code unclear in some way, then use comments to compensate.

Answer 38

Self documenting code is silliness. Anyone who's had to re-visit their code after weeks, months or gasp years knows that (or days, in my case). (Perhaps the guy who is promoting this idea is still wet behind the ears!?!?!)

Use meaningful, descriptive data names, factor your code intelligently, and leave yourself hints as to why the heck you did what you did and you will live a richer, more fullfilling life.

Although...I did read a quote once attributed to Bill Gates: "The code IS the documentation."

Go figure.

Answer 39

Some perspectives from the non-commenting camp.

"well commented" (verbose) code is harder to read and understand. For one thing, there is simply more text to scan. It increases the cognitive effort in understanding a CodeBase - the nonfunctional text takes up screen space that could be used to show code.

Another big problem with comments is that they are unreliable - especially on older code bases, comment rot sets in faster than bit rot.

And then of course there is the effort involved in writing comments. With the exception of the occasional one line clarifier, every time I start commenting code I get one of two guilty feelings

1. this info needs to go in overall supporting documentation
2. I need to clean up my code

Answer 40

Regardless of purely self-documenting code is achievable, there are some things that come to mind one should do anyway:

• Never have code that is "surprising". Ie. don't use silly macro's to redefine things etc. Don't misuse operator overloading, don't try to be smart on this.
• Split away code at the right point. Use proper abstractions. Instead of inlining a rolling buffer (a buffer with fixed length, with two pointers that gets items added at one end and removed at the other), use an abstraction with a proper name.
• Keep function complexity low. If it gets too long or complex, try to split it out into other other functions.

When implementing specific complex algorithms, add documentation (or a link to) describing the algorithm. But in this case try to be extra diligent in removing unneeded complexity and increasing legibility, as it is too easy to make mistakes.

Answer 41

Very mixed inputs here it seems :)

I use the Pseudo code Programming Process for new developments, which virtually makes my code self documenting. I start to write Pseudo code only when writing new code then extend on it. Im not saying this is best practice or anything like that, i'm just highlighting one technique I find useful if you know you want a lot of documentation for your code if its going to a third party, reviewer, etc... it also occasionally highlights problems for me before ive even written a line of code.

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

becomes;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if

Answer 42

I once worked with a guy who was about to sell a financial suite to a large company. They insisted he document the source code, to which he produced a 30+ page assembler routine and said 'it is documented, look' - then he flipped to page 13 and there was a comment 'bump counter by one'. Great product, great implementor, but...

Anyway to my mind the inportant comments above are to set the context. This snippet was stated as self-documented:

> from BeautifulSoup import
> BeautifulSoup, Tag def
> replace_a_href_with_span(soup):
>     links = soup.findAll("a")
>     for link in links:
>         tag = Tag(soup, "span", [("class", "looksLikeLink")])
>         tag.contents = link.contents
>         link.replaceWith(tag)

But, I for one, need a context to understand it fully.

Answer 43

The point has been made that comments should capture intent, but I would go a little further.

I think for any class of problems, there is an ideal (or nearly so) vocabulary and syntax to describe it, and you can see it if you just ask the person who has such problems to describe them (assuming that person can think clearly).

If that vocabulary and syntax maps easily (by defining classes, methods, etc.) onto code in a computer language, then that code can be self-documenting. Also, IMO, a domain-specific language has been created. (And that is my rough-hewn definition of "declarative".)

Failing this ideal, if the problem does not map so directly onto the computer code, then you need something to link the two together. IMO, that is the purpose of comments.

That way, when the problem changes, you can find the corresponding parts of the code to change.

EDIT: I am not, by the way, arguing in favor of the OOP methodology where every noun becomes a class and every verb a method. I've seen enough bloatware built that way.

Answer 44

Self documented code is code that is so clear that a comment would be unnecessary. I'll give a small example:

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

The comment is pretty useless, because the code is clear. Documentation is a good practice, but extra documentation can add unecessary noise to the code. What your colleague needs to know is that not everyone can read other's code and acknowledge all it's details.

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

The last snippet would be extra hard to decipher without the comment. You can imagine other examples that are more contrived.