To summarize the following article: Why You're a Bad PHP Programmer

you're a bad programmer if you don't write comments.

My personal opinion is that code should be descriptive and mostly not require comments, unless the code cannot be self-descriptive.

Consider an example given in the article:

    // Get the extension off the image filename  
    $pieces = explode('.', $image_name);  
    $extension = array_pop($pieces);

The author said that this code should be given a comment. My personal opinion is that the code should be a function call that is descriptive:

    $extension = GetFileExtension($image_filename);

However, in the comments someone actually made just that suggestion (the comment is no longer there). The author responded by saying the commenter was "one of those people", i.e. a bad programmer.

What is your view on Self-documenting Code vs Commented Code?

  • Your preferred method is essentially using function calls to comment your code. Why not use comments for that? Functions should be used for reusable code only. I personally hate having to follow someone else's code written in this manner for the same reason the GOTO statement is evil - It creates spaghetti code. This is made better by modern IDE's, but not every language and programmer can use these IDE's and it's still disorienting. Honestly, I agree that you should comment sections of code that are not clear at a glance - it just makes reading through your code so much quicker and easier.
    – dallin
    Commented Sep 3, 2013 at 20:54

22 Answers 22


I prefer writing self documenting code. A guide for this is Clean Code.

This of course does not mean one should never use comments - they have their role, but IMHO you should use them carefully. This earlier answer of mine on SO explains my thoughts on the topic in more detail.

Of course, as @Niphra noted, it is always worth double checking that what I believe to be clean is really understandable by others. However, this is a question of practice too. Back in the uni I wrote cryptic pieces of code simply due to using strange and funny names for all code entities, according to my whim. Until my teacher threw back one of my assignments, politely noting that he couldn't figure out which module was the main :-) That was a good lesson, so I strove to focus on writing ever more readable code since. Nowadays I hardly get complaints from teammates.

  • 3
    I still find comments valuable to express the strategy used, and those who were rejected (with the reason). I agree that micro-comments are generally useless. Commented Feb 24, 2011 at 17:59
  • @Matthieu M., for me design/strategy related comments are inside that "gray zone" about which I don't have a strict opinion; I consider it a matter of personal style so I am fine with it either way. Surely these kinds of comments age better, or at least don't rot as fast as the micro-comments. Commented Feb 24, 2011 at 20:38
  • 12
    One of my favorite quotes from Clean Code is that every comment is a failure to express yourself in code.
    – Doval
    Commented Feb 20, 2014 at 20:01
  • 15
    @Doval: An interesting philosophy, at least with regard to comments about what code does. On the other hand, some of the most useful comments can be those about why code doesn't do something--a concept which I don't think code should be expected to express.
    – supercat
    Commented Feb 6, 2015 at 21:25
  • 3
    Disagree entirely. No amount of naming is going to fully describe the purpose of logic. Commented May 31, 2018 at 19:43

You shouldn't document what the code is doing, but you should document why it's doing it.

No amount of naming trickery will expose the whys and wherefores, so you have to add comments to explain the purpose of the various bits of code.

All the other comments can safely be get rid of.

  • 4
    +1 The example in the linked article says "make comments in any situation where the purpose of the code I've written isn't immediately apparent." - It's just silliness to believe that code by itself can communicate purpose, because machines themselves have no concept of purpose. Counter example: We have bugs in almost all software ever written, this is a truism. If a computer understood purpose (the why), it would simply refuse to do anything other than what we intended, rather than dutifully recreate the what/when/how/where that led to the bug. Commented Jun 27, 2015 at 12:25
  • All the code inside a function should be there to fulfill the purpose of the function, i.e. what it does, e.g. write some text to a file, the function "writeTo(String text, File file)". If some code has a different purpose, e.g. check preconditions, like verifying that the file exists AND it is not evident, then perhaps a better idea than a comment is writing a new function, e.g. "checkWritable(File file)". Code quality is not a dogmatic checklist, but if it needs comments, that's a bad sign, and the "whys" are not a good reason to need them. Why did the chicken cross the road?
    – Trylks
    Commented Jul 24, 2015 at 15:47
  • 3
    @Trylks That works for some cases but not for all. Imagine this scenario: for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Now, this is neither something that is obvious from the purpose of the enclosing function, nor could it be factored out into its own function. If you leave it uncommented, that's clearly bad. So you add a comment to clarify your intent.
    – biziclop
    Commented Jul 24, 2015 at 16:05
  • 3
    @Trylks Besides, even if we take your example, you factor your check out into a method and call it, great. Now all you have to explain is why you need to check that the file is writable. :)
    – biziclop
    Commented Jul 24, 2015 at 16:08

I don't actually believe in self-describing code. There is more readable code and less readable code, depending on the language, your knowledge of it (as the original author), the knowledge of the guy reading it, and the code function. But no, still ... it should be described with a short comment.

What is clear to me now, that I'm in that area of thinking will probably not be clear to me in a year, when I'm thinking about something completely different and need to use this part of the code again.

So, comment your code. Not every line (good heavens, no) of course, but put a few lines of comment above a function / subroutine / module, or a particularly tricky part and tell in short what it does. You'll thank yourself in a year or two.

  • 1
    Been there, done that. "Less readable code" should be improved into code that reads well. Knowledge of a language doesn't really count: When not familiar with the syntax, you should learn it first - frankly, that's the basis for being a professional. Trying to make up for terrible code by adding comments is not a good idea. Comments should never ever attempt to describe what the code does. A (general) comment is justified only if you need to tell the why and not the what. Everything else is just noise and unnecessary additional stuff to maintain.
    – Powerslave
    Commented Jul 3, 2016 at 22:02
  • 1
    To avoid confusion, I'm talking about the usual case, when you're not forced into writing bad code by the business requirements (e.g. exceptional performance or fitting into confined storage). In other (rare) cases, you have no option but to leave comments, somewhat easing the burden of the next victim.
    – Powerslave
    Commented Jul 3, 2016 at 23:23

Luckily, both camps on this discussion are represented here, and pro and con arguments for both were mentioned.

I believe both camps have overlapping arguments, and actually agree on most of them, just the way how to achieve them is a bit different.

Overlapping arguments

  • Code should be readable.
  • Comments shouldn't say the exact same thing as the code does, but give further insight where necessary.
  • All variable/function names should be given good thought so they give a good representation of what they are/do.
  • Duplicate code should be prevented.

Now, the main difference is how much weight is put on some of those arguments.

Self-describing code

  • Comments can get obsolete, so minimize using them, as wrong comments are worse than no comments.
  • Comments are a duplication of the code. Everything which can be written in code, should be written in code.

More comments

  • Comments are more readable than code. Plain english is better at describing something.

  • Plain code often causes ambiguity which has to be commented anyhow. Trying to describe this in code, results in too long names. Furthermore, you are constantly confronted with this 'extra' information which you only need the first time you come across it.

I believe both camps have very valid arguments, but you shouldn't frantically follow one camp, just because it solves one issue.

To demonstrate, in the book Clean Code, code is broken down into numerous smaller methods which are only called once. Methods are created for the sole reason to document the code (and easier TDD). This results in Function Hell. The code is less readable than it was originally, and while refactoring, no thought was given to encapsulate reusable code.

On the other hand, you often see API's where every function is commented, just because 'comments are good'. The things which should have been commented still aren't.

  • 2
    This is a very good answer! One thing, if you won't mind, on comment readability: I personally don't believe in comments being more readable. We, as developers, usually think in source code, especially when in "coding mode". In those moments, the vagueness of plain human language is usually more of a distraction than of help.
    – Powerslave
    Commented Jul 3, 2016 at 22:16

The Short, Better, and Correct Answer

The idea that well-written, "self-documented code" is all you need is an anti-pattern and should die, even when it makes exceptions for comments that explain "why". It's a myth that you can always write all code for any algorithm clear enough for any programmer to glance at and get it (or that it won't require refactoring or organizational time you don't have). Even more importantly, more often than not, programmers who think they write clear code do not.

A much better answer than comments should only be used to explain "why" is that comments should:

  • explain "why" (of course)
  • explain "what" on individual lines only when the code is complex or the purpose is unclear and it can't be or isn't worth simplifying further
  • explain "what" for blocks of code to speed up comprehension and locating what you need

The Explanation to Back It Up

People erroneously think the only reason people use comments is to explain what a line of code means. The truth is a large purpose of commenting code is to make it quicker to glance through your code and find what you're looking for. When I come back to code later or read someone else's code, sure, I can read and understand a section of well written code - but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking for? Why sit there and figure out code at all, even if it's well written, if you can glance at a couple comments and understand an entire function? That's why we use descriptive names for functions - no one says I don't need to use a descriptive name for my function because someone can just look through my cleanly written code to see what it does.

For example, if I'm looking through someone else's function, is it easier to go line by line through the code to see what it's doing or to glance at three well written comments throughout the function to see exactly what the function is doing and where it's doing it?

Another anti-pattern is the overuse of functions to comment your code. Well named functions are an important part of code documentation, but sometimes programmers separate 2-3 lines of code that will never be used anywhere else into a function for documentation purposes. Why is overusing functions any better than overusing comments? Using functions like that is the same as embracing GOTO statements - it creates spaghetti code that can be a pain to follow.

Essentially, when you work in an enterprise environment, where people are constantly sharing code and people don't always have the time to make their code perfect, a few good comments can save tons of time and frustration. And remember, while you may be a guru who can read through code at light speed, not everyone in your office probably is.

  • I hate it when people downvote and don't even leave a comment why. Did you even read the entire post? What in there isn't straightforward and true? What do you disagree with? I feel like people are so set in their idea or what they read that they don't even think about it and will downvote anything immediately that doesn't share their view.
    – dallin
    Commented Sep 3, 2013 at 23:45
  • 5
    I assume it's because you outright reject and name an antipattern something which is nearly universally recognized as right. I certainly think you go too far. Mostly, I can't imagine trusting comments as well as you seem to. If you blindly read the comments and not the code, the comments may be wrong and out of date, and you'd never know. That's the basis of using functions as documentation. I'll agree that you shouldn't have too many functions in one place, though the solution to that is definitely not to replace them with comments.
    – Magus
    Commented Feb 19, 2014 at 16:02
  • 1
    but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking for It's called "the name of the method/function". If you've got a block of code that has no name but is so long that you can't take it in with one quick glance, maybe the problem lies there.
    – biziclop
    Commented Jun 27, 2015 at 14:51
  • 1
    @biziclop Overtime I came to believe this argument is mostly semantics, and in practice, our code would look similar. Having said that, assuming the block of code is not used in more than one place, I do not see a difference between a block of code with a short descriptive comment at the top and a block of code with a short descriptive function name at the top. They are the same, except one has no spaces. They can both be wrong and out of date. The only difference I really see is the code is easier to read with a comment since you don't have to follow the function call to a separate location.
    – dallin
    Commented Jul 3, 2015 at 18:46
  • 1
    @dallin That is true, on the other hand though, a short code block that is its separate function can be compartmentalised in your mental map of the code far more easily. Without the familiar formalism of a function declaration that task is a lot harder. Of course you can formalise your block comments too, but not everyone will adhere to your comment formalism. No problem, you can write a tool that checks the comment formatting. But how different will that tool be from the compiler? :)
    – biziclop
    Commented Jul 3, 2015 at 18:53

"Im sorry but your that guy."

I wonder why he does not like commenting :P

Seriously, coding is too much of an art that one could truthfully make such a sweeping statement. Sometimes you need comments, sometimes more and better named functions. Usually both.

Look up literate programming as an extreme style.

  • 2
    Yeah. I mean, if Donald Knuth thinks you not only need comments, but sometimes need chapters of them, I would think at least twice before disagreeing. Commented Feb 25, 2011 at 1:50

Well, the thing with self documenting code is that within that function, you would find :

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

which is self explanatory when you have the function name since it's only two lines. When things get more complicated, you either have to wrap every few lines of code in a function with a descriptive name, or use comments where necessary.

I never understood why it should be an or/or matter, instead of and/and. Yes, make your code as much self documenting as possible, and yes, add some comments to the parts that would otherwise be rather unclear.

  • Yeah. I think you have to be "trained" to think it should be one or the other and not both. Commented Feb 25, 2011 at 2:02

Well you also have to remember something that is obvious or "self-documenting" to you, may not be to someone else...Maybe someone with less understanding of certain functions. So I comment just about everything.

  • 1
    Can you give an example. I mean given the example in my original question. "GetFileExtension" whats the point in the comment "Gets the file extension of a given file"? The method has already described what should go into the comment. If the method was named "GetExtension" then a comment would aid in clarifying what the method is to do, since the method is not explaining itself.
    – Phill
    Commented Feb 24, 2011 at 13:22
  • +1 This is a know-your-audience question. Who is likely to use this function? How can you help them? What will your help be worth? Is it worth more than spending a bit of time now to add a comment? Etc. Etc. Etc. Commented Feb 25, 2011 at 1:56
  • 2
    @PeterAllenWebb: No point to that comment at all. That doesn't remotely mean the function shouldn't be commented; it should. Does "extension" include the dot or not? What is the return value for "foo"? (null? ""?) For "foo."? Will passing in null cause an exception, or will the function return something (perhaps null)? Commented Jan 8, 2015 at 13:21

Comments and the self-documented clean code are different. Code is all about how to do things. And comments should cover the why part, which can't be explained in code, whatever your language is. Also, if your language is very limited and you've got no contracts, no static specifications and even no assertions, comments should cover the boundary issues of your code.

  • Assuming there is a reason for everything, it should be commented?
    – JeffO
    Commented Feb 24, 2011 at 14:03
  • Yes, precisely. That's why I believe that the best way to comment your code is a literate programming.
    – SK-logic
    Commented Feb 24, 2011 at 14:12

I disagree with that article and agree with you to some extent. If you use good method names, good variable names, and small methods that do a single thing, then the code should be simple to follow.

Just try not to be clever, because clever code is horrible to read and maintain, with the emphasis on maintain.

My opinion is that comments should describe the why and not the what. Remember, in this hypothetical perfect world, your code should be clean enough to allow for easy reading, you don't need to explain what it's doing, but why you chose to do it this way or that way.

If you're using a source control system, then you can use the commit message to let everyone (and yourself) know what you did at a given time and more importantly, why.


At university we were taught to pretty much rephrase every line of code in English with a comment (probably just to get us into the habit of understanding what code actually does, rather than just copy/pasting something and hoping for the best).

Personally, I reckon that clutters the hell out of your code, making it less readable than if it were just comments or just code. I'm a C# coder and the only comments I make all the time are the "triple-slash" comment blocks that are interpreted back to IntelliSense documentation. If I'm feeling especially guilty about a particular way of doing something, orit looks especially cryptic, I'll give a further explanation, but that's about it.

IMO: Self-documenting code is code where variable and method names are given meaningful and contextual names, so that they describe what their purpose is.


In that case, it's easy to make a descriptive function. But I've read a lot of code made by good programmers who believed their code was self-documenting, and what had been crystal clear to them was really confusing to me.

$extension = GetFileExtension($image_name);

To get back to your exemple, can I send an array of image names to it, or does it take only one image? Does it support any types of file, or only some of them? Will it secure the string for me, or do I have to do it? If the file type doesn't exist, does it notify me?

Of course, I'm stretching this one a bit. But I remember a programmer who believed audio_bandwidth and video_bandwidth were self-documenting names; turned out audio had to be expressed in bytes and video in kilobytes. Took a lot of time to figure that one out.

  • 6
    You're stretching that one a lot. The function gets the file name extension. Nothing more nothing less. Its name says if it takes an array or not (clearly not). I can't think of a method that would rely on the file type to get the extension. Securing the string is the only one that might be incorporated, but I would never expect it because as any PHP dev knows: all user input is suspect, so secure it before you use it.
    – Matt Ellen
    Commented Feb 24, 2011 at 9:52
  • 2
    @Matt: The “clearly not” is an indication that you don't do maintenance very often. Being explicit saves much head-scratching (and RTFSource) later on, and it also documents what the original author expected it to do. Whether that's in a comment or in a long function name isn't nearly so important. Commented Feb 24, 2011 at 10:01
  • 2
    @Donal Fellows: it says file, singular. What is ambiguous about that? It's completely explicit.
    – Matt Ellen
    Commented Feb 24, 2011 at 10:12
  • 2
    @Matt: If the definition really is GetFileExtension($image_name), I would expect it to do something at least vaguely related to images. Why wouldn't it be called GetFileExtension($file_name), if it didn't check the type? Commented Feb 24, 2011 at 10:14
  • 5
    The fact that there are now 7 responses from 4 people discussing the obviousness or otherwise of a single function call suggests to me that you need to use comments. It's also highlighted the fact that accurate naming is an artform in itself.
    – Ant
    Commented Feb 24, 2011 at 13:12

One does not exclude the other. Even though your code is self-commented, there are times when you may need regular comments to explain why your self-commenting code does what it does.

  • I think this falls into my opinion which was "code should be descriptive and mostly not require comment's unless the code cannot be self describing". If you write code which is while written well, doesn't full explain the intension of the code, then the comments aid in making the code more descriptive.
    – Phill
    Commented Feb 24, 2011 at 13:19
  • Code can never explain its purpose. When you see a hammer, you can't figure out what is it for - is it for smashing skulls or just for forging a raw iron.
    – SK-logic
    Commented Feb 24, 2011 at 13:29
  • 1
    @SK-logic: public <T> void hit(T item);
    – Michael K
    Commented Feb 24, 2011 at 15:38
  • @Michael - exactly. How the user will figure out, what categories of objects can and should be hammered? Even with a much better type system it is not always clear, what range of possible uses is actually planned by a developer.
    – SK-logic
    Commented Feb 24, 2011 at 15:49

You would want to avoid writing comments just like you would want to avoid any documentation. When it comes to the programming language itself, everyone is operating from the same set of vocabulary and syntax (almost).

When your app is for a particular domain, it can be difficult to get everyone involved to agree on and/or establish a common vocabulary. We're taught to avoid abbreviations and extensive jargon, but I'm going to call it


and not


If you don't know one, you probably don't understand the other. If the company has some uncommon implementation, a comment would help the next programmer who may have experience in the domain, but not this particular firm (Which just makes things more complicated.).


I think we need to distinguish between documentation and expressivity of the code.

When debugging or reviewing code, you're not reading a book. Most of the time you just want to jump from method to method and make quick connections in your mind to get a basic understanding of what's going on at runtime. It's not the documenting around the code but the expressivity of the code signatures that matters in that process, their ability to be meaningful enough that you can immediately identify them and add them to your own internal call stack. At that point, our brain (at least, mine works that way ;)) tends to consider large comment blocks as a noise rather than a help. Therefore, one-line comments, or even better, just self-descriptive method and object names are sufficient here.

If you want to "read the book" of a particular class or feature, a much better place for that is in the unit tests. Well-designed unit tests are by nature intention-revealing and much more documenting (ie explanatory, detailed) than the thickest of comment blocks since they contain 1/ the expectations on exactly what this code is supposed to do and 2/ the ability to check these expectations against the real code. A passing test is a hundred times more reliable than any comment in terms of documentation, because it proves that what it asserts is true.


Some code just is not self-documented, and requires some commentary from a fellow human who understood and tested that piece. What I have below just is not enough to understand it, I think.

// iterative version
Node* ReverseList( Node ** List ) 

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;

  return *List;

I generally favor writing self-documenting code, with comments where unclear, since I think most code will not completely document itself.


I believe in the mantra that code does not document itself, because you could be the best programmer in the world (Ada), and yet don't understand a thing about what is going on, but if you document why and in a short extent how your code is doing what it does, your going to help yourself and others in the future.


Comments are a must have. Because when you write code, you are writing for your current needs, but also for the people in the future who have to read your code, figure out wtf, are you doing, and why, and then how to make modifications for it.

If you just keep this in mind, when coding/programming?

How can i make this easier to understand and modify for future coders of this code I am working on, then you'll be doing a good job. Failing that, your just making it hard for others to modify your code, and don't imagine that never will be the case, that's rare...

At most of my job's, I have had always to modify other people's code, and most horribly written, poorly documented.

So your habit of thinking the code document it's self, is just not doing due diligence.

As programmer's we must practice the self-discipline that may appear to be totally a.r. to inexperienced programmers, but must have habits, to avoid all the horrible experiences we've had with other people's code. Or even looking at our own code months, years later.

Check out http://thedailywtf.com they have tons of humorous but real stories about programmer's who just didn't do their due diligence..


This is why "code review" was invented.

The problem is that you - when you write the code - have a mental envisioning of what you work with, that will be gone in a while. Hence if you could ask your future self if you have documented enough of what you have in your head to reestablish this later, that would be the best.

Until we invent time machines, the best substitute for your future self is a colleague, so let them have a look and if they think they can understand what you do well enough to let them maintain it you are fine. If not, you refactor and document until they do.

As all these answers show, you cannot set up rigid rules for this. Some things simply need better explaining than others.


If you have revisited your code multiple times and still not have found a way to make the intention clear to some one who knows the domain. Rewrite the function. After all it's no more than 10-20 lines. If it is longer rewrite the function anyways it's to long and that's part of why it's unreadable :) rinse-repeat

and in the unlikely case it's still unclear what the code is doing and you've remembered to ask your peers for help. Well then We all thank you for helping evolving Linux cuz it is kernel code you're writing right? if not rinse-repeat from the top :)

Simply put don't write you're comments CODE them


Check out Code Complete 2nd edition, pg 128-129.

Abstract Data Types will save you from this conundrum. Self documenting code is the way to go. Comments can be useful, but having

real-world entities rather than low-level implementations

you're able to avoid using comments.

One thing about comments is that you write them once, but you don't see them when you implement the function, you only see them when you change the function.

Comments are really useful when they're interpreted by the IDE the way Delphi 2009+ or JavaDoc works, but that's more of a structured markup language, so in a sense you're programming your documentation, which is very smart.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.