[agentultra]

I used to work with someone who would start writing a function or module by writing their code as comments.

  # First we iterate over the directory and get a list of files to process
  ...
  # Then we process them

This "pseudo-code" would then be filled in by the actual source code ei intended to write. And once ei was done the comments would stay in and be checked in for code review.

Nothing was more tedious to read. It's like having a narrator tell you exactly what each character is going to say right before they say it. It is quite maddening to this reader and I had to constantly review this sort of code.

I had to politely approach the person writing this code and explain this to them. Comments are not for describing what can already be read. One's code should be written in such a way as to inform a programmer maintaining the code to its purpose and utility. That means short, single-purpose functions, conventions, idioms, and all of that. But it also means that comments should only be used when you're going against convention or doing something hack-ish on purpose.

I saw fewer lines of comments until a fresh, new young team member joined...

[peteretep]

I do this, and I'm a senior dev. I find it an absolute God-send when I come back to the code months or years afterwards.

I am much, much faster at parsing and reading English than I am at code. When I'm coming back to some code for maintenance work, I am not normally trying to understand code deeply, I am usually trying to get a quick overview of it, and then locate a specific thing it's doing, to parse it more deeply.

Comments like this allow a skim read for locating what you're after, and - as you identified - normally come in as I'm detailing the process, which means, doubleplusgood, you also get to see what I was thinking as I was writing the original code.

> One's code should be written in such a way as to inform a programmer maintaining the code to its purpose and utility

Almost. But you forgot "as quickly as possible".

> But it also means that comments should only be used when you're going against convention or doing something hack-ish on purpose.

I suggest that with experience, especially experience of being the curmudgeonly old senior dev on very mixed ability teams, with codebases sometimes a decade old, where the code is occasionally insane, you will start to be thankful of all clues the code can possible offer up as to why people do what they do.

[agentultra]

You assume I'm young! How nice!

I read tonnes of code. I've formed my opinion by reading and reviewing tonnes of code. I'm cautious about jumping to conclusions.

In my experience the kind of code that requires comments to act as "guideposts," (if I've correctly interpreted your meaning) is suffering from symptoms of a larger problem: poor design. When I read code that comes from people who use this style I often find that their functions go on for ~70 LOC, use at least 3 levels of nesting, and are littered with comments to explain what is going on.

More often than not I was able to show them that they could break these procedures out into compose-able functions and drop the comments. With the right data-structures they could avoid excessive loops and conditionals. And with the right unit tests if they ever needed to change the implementation of a function they would know right away if they broke something. Suddenly they didn't need so many comments because their functions were < 10 LOC and self-explanatory -- the name of the function gave its meaning and the higher-level code read more like an explanation of the process without all of the details of how the machine should perform it.

That, of course, is the best case scenario. I've worked on a gnarly C++ web application that was more than a decade old and survived several attempts to port and extend it with Python. But you can deal with that too. Just try not to touch the legacy code. ;)

[bruceboughton]

>> I am much, much faster at parsing and reading English than I am at code

Perhaps, but then you're parsing and reading what the comment says the code does, not what it actually does, today.

[peteretep]

Sure. When I'm trying to find a piece of code, that's a pretty good start.

[lhnz]

It's better to make a mistake in your thought process that can be caught by reading plain english than to write the code and realise the logic is wrong. However, I agree that comments that are completely banal should be removed in place of more interesting ones about the design decisions, performance characteristics, etc. (I however do start by writing comments explaining exactly the code I am about to create as I like to spot higher-level problems as early as possible.)

>> I saw fewer lines of comments until a fresh, new young team member joined

Young programmers and Knuth[0].

[0] http://en.wikipedia.org/wiki/Literate_programming

[agentultra]

I love literate programming.

However literate programming isn't about commenting your source. It's about explaining your program in plain human language and presenting it in an almost essay style. A special program is run on your "literate" source which translates it to a set of source files that your compiler understands. It is not about writing verbose and excessive comments in your source code.

I don't mind if your approach is to write out pseudo-code or comments or what-have-you. My problem was that checking this stuff into the code-base wasn't a good idea. I don't suspect I changed the minds of the people I had to work with but they did remove the excess comments from the code before checking it in. That made reviewing their code much easier.