[ameister14]

For me the thing I had to learn was commenting more than anything else; working alone I never saw as much use for it. Then I worked with a guy that commented his code very well and suddenly I saw massive value in it.

I'm definitely still an intermediate programmer, but I think I was always fine admitting that to myself. It was getting over the fear of others reading and modifying my code that took me a while.

[swframe]

The big thing I learned (at a company where all changes are code reviewed) is to rewrite the code until it seems obviously correct to someone who doesn't know what I know. I rename variables, methods and extract code into small methods until someone can read the code out loud and it sounds like a comment. for example: if (!thereIsEnoughSpace(user.getDataRequestSize()) { if (canAllocateAdditionalStorage()) { reserveStorageForUser(user, user.getDataRequestSize()); ...

I've found many bugs after I renamed variables like 'i', 'j', 'k', etc to something more meaningful. That made it easier to realized I was using them incorrectly.

This is basically why I think I'm an ok developer...

I pretend to be the smartest developer in my group (let's call him Bob). I look at a line of code and ask myself, why will Bob ask me the change this line of code? What will he prevent me from checking in? How would he solve this problem?

I do this even if I have a really difficult problem and Bob is the "go to" person. I pretend to be Bob and ask myself, What question will Bob ask me when I tell him about the problem? He will ask me if I've searched google, ok I will search first. He will ask me if I've checked for an upgrade to a library, I will do that. He will ask if I've set a break point here and checked for a memory corruption there. etc. 80% of the time, I find the problem myself and the rest of the time, Bob doesn't know the answer either. But at the end of the day co-workers are fooled into thinking that I'm as good as he is. But I have no doubt that Bob is better because it is important to him to learn everything he can about some key technology. I only approximate Bob when I need to interact with others. If you ask Bob a question, you get a quick and correct response. If you ask me, I will tell you I'm in the middle of something else and I will get back to you in a few minutes but really I have to figure out the answer first hahaha. I try my best to avoid getting help from Bob because, honestly, I don't think Bob respects people who aren't as passionate as he is (most people confuse passion with intelligence). The downside, is that it takes me a day to solve a problem that Bob can solve in a few minutes. Managers hate that but it is just too boring to learn technology to the degree that Bob knows it in my free time.

[illumen]

Both good comments :)

Another couple of ways to improve your coding...

Start with comments outlining what you're going to do. If you are pair programming, this shows the other person what your overall plan is. It also acts as a mini todo list. They should be "What comments". That is, what does this piece of code do, not how it should be done. Comments are better than just coding because you can do that quickly as a sketch to show your partner. Then they don't just sit there waiting for you to type out a lot of the algorithm.

You can also start doing this with tests first, which help you outline the interface for your object/method/function/module. This also helps you think about how easy your piece of code is to use by users of your code. ALotOf. ProgrammersDoNotThinkHowEasyYourFunctionIsToCall(x,a,3). Is it obvious what it does, and what the required arguments are for the caller? Is error handling sane for the caller?

Coding considering Revision control is very important, and these days acts like great documentation. With tools like git blame, you can see comments for pieces of code inside the revision control system. If you limit commits to nice small chunks on one topic at a time this is very helpful for people. Don't include white space fixes with 5 days of changes to 30 files at once, with a comment like "update". If they are nicely explained by the revision control comments, and perhaps even reference your issue tracker, then other people reviewing, reading, or bug fixing your code later will have a much easier time.

Finally, know when you are in prototype mode, pitch/demo mode, quick script mode, or Serious engineering mode. Each call for different approaches, and have different requirements. Don't let the Serious engineer get you to do a 10 day development cycle when you have a time limit of 1 day to deliver. That's a fail. Also, it's a fail if you hack something up without following all the development guidelines for some embedded life critical piece of software.

[mattmanser]

Personally I only recommend the code with comments thing to novice programmers doing play projects.

Generally I think comments are bad and it's too easy to leave nonsense in the code with that technique.

[nikster]

The naming thing is huge. Give things good names. One can also factor out some specialized code into its own method / class - but because you want to re-use it necessarily but because you want to describe what it is doing. Divide et impera.

Having to explain to another what you're doing - I found that to be great as well. It removes bugs and produces cleaner code. You don't even need another - at check-in time, for every change, you can ask yourself "what is this doing" and "why". And if the answer isn't convincing, change what you're doing.

The value of peer-review was rarely on the peer's side - the other person doesn't really know what you're doing and is unlikely to catch a bug. But the peer would ask some question so you would start thinking about it and discover a problem.

The best thing about asking somebody for advice is often to come up with a good question. If you ask the right question, it contains the answer.

[akbar501]

I totally agree. When I first started programming my comments largely echo'd the code, so I saw them as less valuable. Now I'm able to stand back from the code and write comments that reflect the "why", and let the code do the talking for the "what / how".

I see this a lot where the more experienced someone is the more they comment, but also where the comments are higher quality.

[sliverstorm]

It's good you recognized that. In many cases, an intermediate programmer with expert-level group skills (including things like commenting) is worth much more than an advanced programmer with poor group skills. But often people neglect their group skills; they aren't "sexy".

[brianpgordon]

I had the opposite experience; I found it easy to scan through comments explaining what the code does, and hard to read the code itself. So I would comment every single thing to explain it in English so that I didn't have to resort to code. Of course I could drop into code mode and rely on logical axioms and learned patterns, but it wasn't as intellectually satisfying as "getting it" with pure intuition.

Something similar still serves me well as a general mental framework for approaching programming and debugging at a very local (procedure) level:

1. Make sure that the English language description of the algorithm is logically correct.

2. Make sure the code actually corresponds to the English description.

[einhverfr]

You can take this a little further by separating your comments into two groups:

1. An english language description of what the function (or code block) does as a black box (forget the internals as they are subject to change). What you put in and what you get out, or section headings to structure how you read the code.

2. Comments in the code block to tell you why a given decision was made.

What this gives you is the framework you are describing but it further cements it into three layers:

1. Function and block documentation describe contract and what the code is expected to do from outside. If the code does not implement the contract the code is wrong.

2. When reading through the code as contract-implementation you can understand why certain decisions were made.

As bonus points, you get good API documentation.

[nikster]

Yeah well...

Great code needs no comments.

Bad code needs lots of comments.

I've seen examples of both recently.

I randomly met a guy who told me of his idea to implement a UX framework with windows, buttons, views, etc in python.

A week later he sends me the finished framework. And it's perfect. It's easy to understand, all the names of things make sense, it's orthogonal. Not a single comment anywhere, but perfectly clear. Great code basically.

And there's a project I am maintaining where some parts of the code are pretty much impossible to understand, full of duplicated code - somebody loved copy&paste - duplicated method and class names, and threads going off in all directions. There is a comment for every line of code but despite the fact that I consider myself pretty good at reading other people's code, I am not touching that thing with a 10 foot pole.

My goal is to write code that doesn't require a lot of comments.

[tbrownaw]

Great code needs no comments.

Sure it does.

« The simple and obvious way to do this misses important edge cases X, Y and Z. »

« This is to work around a bug in the framework we're using; see http://... . »

« This is deliberately wrong, for compatibility with ABC system. »

[dragonwriter]

> Great code needs no comments.

Great code implementing a particular algorithm for a particular reason might want a comment (1) identifying the algorithm and providing a reference to a published description, and (2) identifying the reason the algorithm was chosen.

Great code that is clear and readable and well-fit to purpose can still, very often, benefit from comments. Not everything that might want to be made clear to readers of code can be expressed in the code.

[danneu]

    > Great code needs no comments.

The most valuable comments that code can't obviate are comments that explain why the code was written this way, the intent, and a summary of how the code fits into the overall picture -- maybe at least a file-level comment.

I think declaring intent is the most valuable comment. What was the author going for with this function? Why is there a nil-guard here when the database column is `NOT NULL`? Is there an actual edge-case or is our data bad or was the author just being arbitrarily defensive against a boogeyman nil?

When reading other people's code, I've found that most of my time is spent figuring out not what the code does, but rather the author's goals and their higher level game plan.

[tautvidas]

While I do agree to some extent that great code doesn't need any comments, it raises some questions. How can one be sure at the time of writing that the code is easy enough to understand for others? I'm sure that it's understandable for the author, who's been staring at it for a few hours, but will the same hold for a future maintainer?

I agree with other commentators that with comments one can at least express the intent and reasons for particular decisions.

And on a side note, it's wonderful to strive to write great code, but I believe it's easy to misjudge and think "Oh, I clearly write understandable code, thus I'll skip comments" even when it's not that clear. That certainly has happened to me, very likely to others at some point as well.

[nollidge]

Sorry, I downvoted this. Great code doesn't need no comments. Lots of comments is definitely a code smell, but anything of reasonable cognitive complexity will almost certainly require some comments.

I can't be certain about your first example, but writing a UX framework is a pretty straightforward thing in terms of what it needs to do, so there probably wouldn't be much need to comment about what it's doing. Why, though - that's a whole 'nother question. Surely it's missing some of those whys.

[hrktb]

It depends on the people working with you, sometimes I feel commenting should be left for edge cases only. More often than not it seemed that people read the comments and stop focusing when reading the code; they just check if it vaguely matches the comments. When foregoing comments entirely there was much better feedbacks and questions on important points, the understandig of the code base seemed much better.

The latter also forces you to keep a very clean code, and tricky parts (things you couldn't simplify nor make self explanatory) surface better.