4 ms·

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 h

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.

akbar501 13y ago
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 13y ago
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 13y ago
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 13y ago
  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.
swframe 13y ago
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 13y ago
  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.
hrktb 13y ago
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.
nikster 13y ago
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 13y ago
  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://.. http://... . » « This is deliberately wrong, for compatibility with ABC system. »
- dragonwriter 13y ago
  > 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.
- nollidge 13y ago
  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.

akbar501 13y ago

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 13y ago

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 13y ago

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 13y ago
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.

swframe 13y ago

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 13y ago
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.

hrktb 13y ago

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.

nikster 13y ago

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 13y ago
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://.. http://... . » « This is deliberately wrong, for compatibility with ABC system. »
dragonwriter 13y ago
> 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.
nollidge 13y ago
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.