407

In layman's terms: There's nothing wrong with comments per se. What's wrong is writing code that needs those kind of comments, or assuming that 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 sync with ...


263

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); boutique.setUrlLogo(CmsProperties....


165

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 ...


160

No, it is not a reasonable request! TALK HIM OUT OF IT, or have someone else talk him out of it, by all means. That is an irrational idea, which although doable is so expensive to do it should never actually be done. An overview of functions and subroutines is reasonable, but to "explain" every code line is not. It would be more effective for him to learn ...


150

Do you have design documents? Those are the English explanation of what the code does. A non-programming manager should not need more than that.


143

If I was going to look at upgrading to a newer version of a third party SDK, the last place I'd look is in the history of the source control system. If your product is using version 2.0 of an SDK and someone is interested in upgrading to 3.0, I don't think it's reasonable to think that they should look backwards in time in your source control system to ...


143

Those are usually called Splash Screens. A splash screen is a graphical control element consisting of window containing an image, a logo and the current version of the software. A splash screen usually appears while a game or program is launching. Splash screens are typically used by particularly large applications to notify the user that the ...


140

The North American Numbering Plan reserves 555-01 numbers for fictitious purposes. If you want an example Seattle number, for example, +1 206 555 0100 - +1 206 555 0199 would do. In the United Kingdom, Ofcom, the regulator, has set aside numbers for this purpose. For example, if you want a Leeds number, +44 113 496 0000 - +44 113 496 0999 may be used. I'm ...


139

This is awesome. I wish more software developers took the time and effort to do this. It: States in plain English what the class does (i.e. it's responsibility), Provides useful supplementary information about the code without repeating verbatim what the code already says, Outlines some of the design decisions and why they were made, and Highlights some ...


131

Absent any specific need, any file that can be built, recreated, constructed, or generated from build tools using other files checked into version control should not be checked in. When the file is needed, it can be (re)built from the other sources (and normally would be as some aspect of the build process). So those files should be ignored with .gitignore....


120

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 caused ...


113

Is there a micro-manager of the year award? It sounds like your boss deserves a nomination. Someone who believes he needs line-by-line level understanding of the code, but doesn't want to learn how to read it directly, is about as perfect as micro-manager as can be imagined. One advantage of being a developer is that the difficulty of understanding code ...


110

You should strive to become irreplaceable not by writing code noone else understands, but by gathering more experience and knowledge than others. The former way makes you a developer everyone tries to avoid working with, as they will fear and loath maintaining code you wrote. The latter way you become a sought out team member, whom managers want to have in ...


110

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 ...


108

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 "dead ...


106

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 ...


91

Sit down with him and talk him through 10 lines of the code. Explain every detail until you both agree he understands it to the extent he wanted to. Maybe this experience is all he's looking for: just an impression of what your work looks like to you, and what the software looks like from your point of view. That's a good thing in my book. If after this, ...


77

I'd go with: #6. Declarative: ... Rather than say "The reason this was done is because each Foo must have a Bar", just say "Each Foo must have a Bar". Make the comment into an active statement of the reason, rather than a passive one. It's generally a better writing style overall, better fits the nature of code (which does something), and the the reason ...


73

In a statically typed language, Javadoc-style documentation is not for the authors, it's for the consumers. Autogeneration simply makes it easier for the authors to maintain the documentation for other people to consume. If you're using a statically typed language and are not writing a library for third party consumption, autogeneration doesn't buy you ...


69

It should be noted in the commit history but the absolute best place to put the notice is in the same place you define the dependency. If you have for example a maven .pom file that declares your artifact dependencies, I'd do something like: <!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 --> Directly ...


68

To-do lists are magic. Generally you need to keep an active to-do list for each project and even while you're busy programming, if you think of something that has to be done and you can't do it immediately, then it goes on the list. Keep this list in a well-known place, either in a spreadsheet or text file in the project folder electronically, or in your ...


66

Because the standard writers don't want to actually assert an implementation. They want to define what it does, but not necessarily how it does it. So, for example, if you look at the GNU C++ version of find_if, you will see that the implementation is slightly different from what you give, which is based on the C++ standard: template<typename ...


65

I don't know anything about Blub itself, but I've been in a similar situation where there was something about my job that I think should be fixed, but don't want to burn bridges. Here are a few ideas that may help. Try to fix the issue. Explain to your boss that you think Blub is a bad decision for the health and growth of the company. Provide specific ...


62

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 git-compat-...


61

So what's wrong with explaining complicated code with a comment? It's not a question of right or wrong, but of the 'best practice', as defined in Wikipedia article: A best practice is a method or technique that has consistently shown results superior to those achieved with other means, and that is used as a benchmark. So the best practice is to try ...


58

I don't think Meyer's point is that you shouldn't tell the user when you have an expensive operation. If your function is going to hit the database, or make a request to a webserver, and spend several hours computing, other code is going to need to know that. But the coder using your class doesn't need to know whether you've implemented: return currentAge; ...


56

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 ...


56

IMO the best documentation is the documentation you don't actually need. I also hate writing documentation and comments. With that being said: Pick readable and talking names. Don't use n, but instead numberOfItemsFound for example. Don't shy back from storing parts of a calculation in a constant variable rather than pushing everything into one line. Move ...


55

There are two main factors in my experience: Deadlines Most companies are so date driven that QA, tech debt, and actual design are cut just so the project manager doesn't look bad or to hit some absurd over-promised client deadline. In this environment where even functional quality is cut, then a long-term investment like documentation has little chance. ...


54

Comments should never duplicate your code. Comments should not answer the "how?" question, but only "why?" and "what?". Why such an algorithm is chosen, what are the implicit assumptions here (unless your language is powerful enough to express it with type system, contracts and alike), what is a reason for doing this thing at all, etc. I'd recommend to take ...


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