This sounds like the inverse of cowboy coding. The classic cowboy move is to tackle all of the easy parts incohesively, so the end program does may three quarters of what it is supposed to. Unfortunately implementing the last quarter will usually require re-writing large parts of the original code over years.

Sometimes the cowboy will linger around to try keep the unshippable code as-is. :( I do not understand why.

If $( cat $your_code | grep '//' ) results in something that does a good job describing the code then you're doing a good job.

If you think you're documenting way too much then it's about right. The people picking up your source years after you've left the company will need that much documentation. Documentation also breeds more documentation. When someone goes in and changes something they're far more likely to document it if their change makes existing documentation/comments incorrect.

That depends. I've found I actually comment/document less now than I used to in the past, because I'm better now at writing self-documenting code. If you can read the code itself and it reads like a comment, you don't need to write the comment.

I see both code and comments as a three-way conversation between myself, the person reading the code (who may be future-me or someone else), and the compiler.

Programming languages aren't just used to tell a computer what to do. They are languages (albeit simple ones with limited expression available).

People who learn a second human language often fall back on a crutch known as "code switching". With code switching, when you don't know how to express something in the language you are learning, you switch back to your native language. This can often help people develop more fluency because they don't sit around concentrating on trying to find the correct term. They can say the parts that are difficult in their native language and then move on to the rest of the conversation.

However, code switching ultimately slows down your progress as a language learner. If you don't know how to express what you want with the correct grammar or vocabulary, it's usually better to try to find a different way to say it. By doing this you exercise your ability to be flexible in your speech. The code switcher tends to hit a ceiling very quickly and never becomes able to express themselves in the new language -- because they never have to. Finding alternate ways to express yourself is often frustrating, slow and embarrassing, but will help you in the long run.

Comments are like code switching. It's really helpful when you've written some code and you think, "I'm not sure that people will be able to understand what this means". It helps you get unstuck from your current position and to move on to the next thing, safe in the knowledge that you have expressed what you need to express.

However, you can also look at the situation differently. If you write comments, then you do not have to express yourself clearly in the programming language. It's easy to fall into the trap of thinking that it is unimportant to express yourself clearly because 1) you have comments (which are easy to write) 2) expressing yourself in code is hard 3) it will take a lot of time to learn how to do it well 4) you might fail and end up with difficult to read code.

These are all seemingly excellent reasons for writing comments, but they will also hold you back from being a better programmer IMHO. I prefer to avoid comments, using them as a technique of last resort. However, if someone says, "I don't understand your code" you have to take it pretty seriously and find a way to express yourself more clearly.

As a side note, this is one of those areas where reasonable people can differ. Of the issues that can cause conflict on a team, I find this to be one of the biggest. No matter what your personal opinion is, it's important to work as a team and do your best to please your teammates. Code is not for the writer -- it's for the reader.

You are not writing code for just you. There may be times when people fresh out of college who do not speak English as their primary language may need to understand your source.

There is often back-story that needs to be explained. Something as obvious as input sensitization may have a more specific meaning behind the specific implementation, for example a legacy Orcale DB client that chokes on certain special characters. A comment in a case like that can prevent you from getting woken up at 1am because a well meaning attempt to apply the same naming rules to schemas as you do to everything broke things.

If someone says they "don't understand your code" then either they suck at understanding code, you suck at writing it or both.

Comments are a tool to increase the speed and accuracy with which someone else can understand your code.

I don't really think this goes against what mikekchar said, though. Take your own example (the legacy oracle client):

The code you're using to escape those specific characters should ideally be written in such a way that its intent is obvious even to a novice reading it. For the novice, then, the question shifts from "WTF does this do?" to "why is this here?", which would be a great example what to actually write comments for: context.

Imagine you're writing some very math-heavy library. Ideally, I shouldn't be a language expert to be able to see what your code does. This still doesn't help me if I don't understand the underlying math, however. Even hints like "this operation is called XY and can be used to Z" may be very helpful if someone wants to get a hold of what it does. With that, you can look up literature for this specific part.

Yep. I don't disagree with either of you. I was really responding to the comment that your comments should form a kind of running commentary of the code (something which I completely bought into when I was younger, but then moved away from). There are certain things you can't express with code. I don't want to suggest that you stubbornly refuse to express it at all in those cases :-). It's just that it's a technique of last resort, not a technique of first resort (if that makes any sense).

With respect to code documentation, I am self-taught, and use thorough documentation because I feel it both reinforces my intent and gives me the experience of describing it to someone else. I get the benefits of teaching, while also sparing my S.O. hours of listening to me rant and rave about things she isn't interested in.

I dont have a mentor, so this has helped tremendously.

This is a good idea. One thing you might try is also to do the same thing with unit tests. Can someone discover the intent of the code from the tests? I have found this considerably trickier to do than it seems because there is a tendency to introduce a lot of noise with the tests in order to get good coverage. I personally found it illuminating to refactor the code and tests so that I get the same kind of coverage without the noise.

You don't need the cat pipe. Just grep on the filename

But I agree entirely. I go back to things I did even a year ago and desperately wish I had documented more.

I see that "useless use of cat" awards haven't died out yet.

Now I'm left wondering if that makes a point for or against the OP's arguments. ;-)

As a side effect of my 9-5 job I think of everything in terms of inputs and outputs that get piped into things and get piped places.