Tag Info

Hot answers tagged

237

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


148

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


109

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


77

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


64

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


58

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


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


51

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


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


47

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


43

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


39

You are absolutely right. Tracking changes is the job for your version control system. Every time you do a commit you should write a commit message explaining what was done, and referencing your bug-tracking system if this is a bug fix. Putting a comment in the code saying // begin fix for bug XXXXX on 10/9/2012 ... // end fix for bug XXXXX every time ...


35

The best solution is, obviously, to just not nest your comments. Nested comments are usually a sign that you are using comments wrong. The most common example is commented-out code that contains comments itself, and the fix is to remove the code instead of commenting it out. That said, many programming languages have more than one type of comment syntax, ...


33

I prefer either: if ($magic == big) { bigMagic(); } else { smallMagic(); } or: if ($magic == big) { // big magic requires a big surprise, so I'm telling you about it here surprisingThing(); } else { // give a magical feeling even if $magic is noMagicAtAll smallMagic(); } It seems a little silly to write a comment explaining what ...


32

Constantly I really can't believe I'm the only one swimming in outdated and misleading comments. In the off chance this helps with understanding: It probably depends most importantly on the age of the code. The next factor would be turnover on the staff. I do equal parts R&D and maintenance work. The R&D is new code, generally stuff that's a ...


31

I would say if you code is so long that you can't easily follow your braces, your code needs refactoring, for most languages. However, in templating languages (like PHP) it could be valid, because you might have a large block of HTML that separates the beginning and end of the condition or loop structure.


31

General Comments I am a great believer in comments are for why (not how). When you start adding comments about how you fall into the problem that nothing is enforcing that comments be maintained in relation to the code (the why will usually not change (the why explanation may be enhanced some over time)). In the same way date/authorInfo does not gain you ...


29

Setting a strict policy like this helps avoid forgetting comments on functions which are not obvious, or which are obvious only to the person who wrote it. Filling out just enough to silence the automatic warnings is defeating the point; you should be actually putting a useful comment there. Take your request_ait(), for example. It may be obvious to you ...


29

In the sample code you posted, it looks like forget is a flag argument. (I cannot be certain because the function is purely hypothetical.) Flag arguments are a code smell. They indicate that a function does more than one thing, and a good function should do only one thing. To avoid the flag argument, break up the function into two functions that explain ...


28

Code organization is all about displaying enough information to convey a single idea. The sweet spot is getting your code pared down enough that a single idea can fit in a single unit of code. Your unit of code can be a function, a class, etc. These are merely tools of organization. As with any tool, it can be over used or used incorrectly. Having a one ...


26

What XXX represents, depends on the author of the code. In general, it is used as a marker for code that requires attention. However, this web page states a somewhat different train of thought: XXX : used to flag something that is bogus but works FIXME : used to flag something that is bogus and broken I guess this further shows that its meaning is ...


26

The signature may tell other pieces of code what operations are available; however, they are not clearly shown to the coder as he or she is working and XML documentation is meant for people to consume and not a compiler. Take this class for example: public class MyClass { /// <summary> /// The first one /// </summary> public int ...


26

A comment that tells you why explains the reasoning behind the code - for example: // We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s // GUID, as the temp <doodad> has the most recent values according to the server and said // values might have changed since we added the <doodad>. We want a ...


25

This is clearly wrong. It is the job of the version control system to keep track of changes, and it is the job of diff tools to show what has changed as a result of the merge. There should be a comment in the commit log, and maybe in the code, explaining what was changed and why. However, IMHO, leaving the conflict markers in as comments is the same as ...


25

Comments are definitely documentation. For most projects, comments are (unfortunately) the primary (if not only) form of project documentation. For this reason, it's very important to get it right. You need to make sure that this documentation stays accurate despite code changes. This is a common problem with comments. Developers often "tune" them out when ...


24

The problem is that recursive comments force you to actually parse the comments section, pushing it outside the scope of a normal lexer and possibly introducing more problems. As a refresher: A compiler usually has a number of distinct stages with different jobs, and the first stages are the lexer, which gets the input program and separates it into a ...


23

I believe NotImplementedException is actually a good practice. Indeed, if you forget to implement a method, and you use it later on in your project (and believe me, it happens), you might spend a long time debugging looking for what went wrong step by step. If you have the exception, the program will stop directly, prompting the exception (if you catch the ...


23

In layman's words: false is a literal. you are passing a literal false you are telling someFunction to not forget you are telling someFunction that the parameter forget is false you are telling someFunction to remember In my opinion it would be better of the function was like this: void someFunction(bool remember); the you can call it void ...


22

I usually consider such comments a bad practice and I think this kind of information belongs to the SCM commit logs. It just makes the code harder to read in most cases. However, I still often do something like this for specific types of edits. Case 1 - Tasks If you use an IDE like Eclipse, Netbeans, Visual Studio (or have some way of doing text searches ...



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