Tag Info

Hot answers tagged

389

Comments alone don't make for better code, and just pushing for "more comments" is likely to give you little more than /* increment i by 1 */ style comments. So ask yourself why you want those comments. "It's best practice" does not count as an argument unless you understand why. Now, the most striking reason for using comments is so that the code is ...


254

In layman's terms: There's nothing wrong with the comments per se. What's wrong is writing code that needs that kind of comments. What's wrong is assuming it's OK to write convoluted code as long as you explain it friendly in plain english. Comments don't update themselves automatically when you change the code. That's why often times comments are not in ...


245

The biggest problem with this code is that you duplicated those 6 lines. Once you eliminate that duplication, that comment is useless. If you create a boutiqueDao.mergeOrPersist method you can rewrite this as: if (boutique == null) { boutique = new Boutique(); boutique.setSelected(false); } boutique.setSite(site); ...


169

Only if the comment describes what the code is doing. If I wanted to know what was happening in a method or block, I would read the code. I would hope, anyway, that any developers working on a given project were at least familiar enough with the development language to read what is written and understand what it is doing. In some cases of extreme ...


151

This is an absolutely horrifying idea. It does not make clear what the intent is. Did the developer comment out the line by mistake? To test something? What's going on?! Aside from the fact that I see 6 lines that are absolutely equal in both cases. Rather, you should prevent this code duplication. Then it will be clearer that in one case you additionally ...


144

Your friend is wrong, and very few programmers would agree with him. You should write comments whenever and wherever you feel they best aid understanding.


111

This is particularly irritating to hear at the moment, I spent some time this weekend looking at very well-named, very clean, uncommented code implementing a research algorithm (one that isn't actually published). I'm high-level familiar with it, the guy sitting next to me was the inventor, and the code was written a few years ago by someone else. We could ...


110

No, it's a terrible idea. Based on that piece of code the following thoughts come up to my mind: This line is commented out because the developer was debugging it and forgot restore the line to its former state This line is commented out because it once was part of the business logic, but it is no longer the case This line is commented out because it ...


105

I've seen this done before, both manually by authors and automatically by scripts and triggers integrated with version control systems to add author, check-in comment, and date information to the file. I think both methods are pretty terrible for two primary reasons. First, it adds clutter and noise to the file, especially as these comments age and become ...


101

I have met lots of devs who had trouble of writing self-documenting code or helpful comments. Those kind of people most often just lack enough self-discipline or experience to do it right. What never works is just "telling them to add more comments" - this will increase neither their self-discipline, nor their experience. IMHO, the only thing that does ...


95

Comments should be written for human beings to understand. When human beings communicate, we typically use "I", "we", "you", etc. When someone is trying to understand some code, there are two or more actors: the person reading it, and the original author of the code. Saying "we" is fine. Unless by 'professional', you mean 'robot-like'.


85

Well written code should be sufficiently self-documenting that you don't need any comments explaining what the code does, because it is obvious from reading the code itself. This implies also that all functions and variables have descriptive names, although it might be needed to learn the lingo of the problem and solution domains. This does not mean that ...


84

Ignore your friend. Comment as needed. But endeavor to make your code self-explanatory, so that comments aren't needed. Remember that your computer isn't executing comments, and so it's easy for comments to get out of sync with what's actually going on. I tend to use a block of comment to explain a particularly tricky bit of logic, that would otherwise take ...


83

The function name should say what you're doing. The implementation will tell you how you're doing it. Use comments to explain why you're doing it.


83

I tend to use // todo comments for things that have to happen, but I can't do immediately. I also make sure that I chase up on them - I search for them (Visual Studio has a nice feature where it will list such comments for you) and ensure that things are done. But, as you say, not everyone is diligent about them and like many comments, they tend to rot ...


78

Use them as much as possible. Yes, those are special comments that become the documentation for the method. The contents of <summary>, the parameter tags, etc. that are generated show up in intellisense when you or someone else is getting ready to call your method. They can essentially see all the documentation for your method or class without ...


78

Comments should explain why, not how. How type comments are usually better dealt with using refactoring. Personally, I usually avoid comments in favor of refactoring. Before: # convert to cents a = x * 100 # avg cents per customer avg = a / n # add to list avgs < avg t += 1 after: total_cents = total * 100 average_per_customer = total_cents / ...


76

Focus on "Why". Its all very well looking at the diffs and seeing that someone changed the logical flow of a section of code or something like that, but why did they change it? The why is usually in the associated ticket (JIRA for you). They may wonder why the "Why" is important but in 2 years time when you have caught some bug that is a knock on effect of ...


72

Most of the answers focus on how to refactor this one specific case, but let me offer a general answer to why commented out code is usually bad: First, commented out code isn't compiled. This is obvious, but it means that: The code might not even work. When the comment's dependencies change it will not obviously break. Commented code is very much ...


71

There's a bunch of different reasons for code to be complicated or confusing. The most common reasons are best addressed by refactoring the code to make it less confusing, not by adding comments of any kind. However, there are cases where a well-chosen comment is the best choice. If it is the algorithm itself that is complicated and confusing, not just ...


61

I think programmers would figure out another way to add comments... string aComment = "This is a kludge.";


59

The most common and most distinctive example is comments around various workarounds. For example this one: https://github.com/git/git/blob/master/compat/fopen.c: /* * The order of the following two lines is important. * * FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h * to avoid the redefinition of fopen within ...


52

Should comments say WHY the program is doing what it is doing? Unequivocally yes. There don't necessarily need to be many comments, mind you, but if you have them, WHY is the only question worth answering outside of a few bizarre fringe scenarios. The reasoning is simple. If I read your code, good or bad, I can see what the program is doing. I have no ...


51

I would not recommend that style as it makes it difficult to scan for braces. void DoSomeInterestingImageManipulation(char *pImage) {//This will convert the image to formatABC which allows x% space savings for storage if(pImage && pImage[0] == 0xFF) {//Process the extra case where image internal format needs decompression ++pImage; ...


50

Use the best tool for the job. Your version control system should be the best tool for recording when bugfixes and CRs are made: it automatically records the date and who made the change; it never forgets to add a message (if you've configured it to require commit messages); it never annotates the wrong line of code or accidentally deletes a comment. And ...


49

I would just like to add to CodesInChaos's answer, by pointing out that you can refactor it further into small methods. Sharing common functionality by composition avoids the conditionals: function fill(boutique) { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...


45

I don't think it's that simple: even in well-written, self-documenting code, there are legitimate situations where you should write comments.


45

Too many comments are much worse than too few. They take time to write, and even more time to maintain. Throughout the life of a project, code will always reflect what the program does, comments will be inaccurate the instant the code changes. Once the intent to the code does not match the comment, you are on a slippery downhill slope. Comments are not ...


44

The benefit of #ifdef's as opposed to commenting it out, is that (on large projects) you can have the defines listed in a make or config file - and so don't have to manually go an uncomment things, build, and then re-comment them if it's in many places. The downside to this is that changing the project's DEFINE's will usually mean rebuiling the whole thing, ...


44

Modern IDEs recognize the TODO comments and they are as such visible in their own panel/window/tab, so they are theoretically not lost (I'm thinking Eclipse and Visual Studio, both I know enough to remember that they recognize it). You can even configure additional comment words such as FIXME, BEWARE or anything else you want to customize. However, other ...



Only top voted, non community-wiki answers of a minimum length are eligible