258

There are a few reasons. Nobody reads documentation. Nobody follows the documentation even if they do read it. Nobody updates the documentation even if they do read it and follow it. Writing a list of practices is much less effective than creating a culture. Coding standards are not about what people should do, but are about what they actually do. When ...


173

Michael Durrant's answer is IMHO not bad, but it is not literally answering the question (as he admitted by himself), so I'll try to give an answer which does: I also understand that comments should explain why the code does what it does, not how. Given all this is it even possible to write good coding standards that capture this idea? Obviously you can ...


151

Major anti-pattern leading to poor quality code with less clarity btw readers, the title was originally "comment every line of code?" and you can imagine the instinctive reaction of many of us, myself included. I later retitled to the longer more accurate title. At first, reading your question I thought, yuch duplicate stuff in comments , but ok, maybe if ...


125

The sole purpose of software abstractions is to hide functional details. Were it not for those abstractions, it would not be possible to progress beyond a certain point in computing, because systems would simply collapse under the weight of their own complexity. Human brains can only comprehend so much information at once. Consider what happens when you ...


116

In short, there aren’t any particularly useful subtraction-like operations on strings that people have wanted to write algorithms with. The + operator generally denotes the operation of an additive monoid, that is, an associative operation with an identity element: A + (B + C) = (A + B) + C A + 0 = 0 + A = A It makes sense to use this operator for things ...


115

There's another interpretation. I don't believe it is what Uncle Bob meant, but it is worth considering. Don't capture coding standards in a document. Capture it in code, by having an automated process which verifies the standards are being met. Don't rely on people referencing a document, but at the same time, don't rely on people interpreting the code ...


101

IMHO your friend is right in using a symbolic name, though I think the name should definitely be more descriptive (like BOARD_WIDTH instead of CHESS_CONST). Even when the number will never change through the lifetime of the program, there may be other places in your program where the number 8 will occur with a different meaning. Replacing "8" by ...


100

Don't overthink this, Range range is fine. I use such kind of naming for more than 15 years in C#, and probably much longer in C++, and have never experienced any real drawbacks from it, quite the opposite. Of course, when you have different local variables in the same scope, all of the same type, it will probably help to invest some mental effort to ...


100

This is a very common experience Most people I interact with, and I myself as well, feel like this. From what I can tell one reason for this is that you learn more about the domain and the tools you use as you write your code, which leads you to recognize many opportunities for improvement after you've already written your program. The other reason is ...


93

... when arguing with one of my collegues, who is going to the point of declaring constants like: private const char SemiColon = ';'; private const char Space = ' '; private const int NumberTen = 10; The argument you need to be making with your colleague isn't about naming a literal space as Space but his poor choice of name for his constants. Let's say ...


92

The rationale behind splitting functions is not how many times they will be called, it's keeping them small and preventing them from doing several different things. Bob Martin's book Clean Code gives good guidelines on when to split a function: Functions should be small; how small? See the bullet bellow. Functions should do only one thing. So if ...


86

I agree with your code reviewers, but with an asterisk. Each statement that you write in your code is a technical liability -- it's a potential failure point. If you write a method with 10 statements and your coworker writes one that achieves the same functionality with 5 statements, his is likely to be 'better' as measured by likelihood of issues (there are ...


77

I feel the code should read: PowerManager::PowerManager(IMsgSender* msgSender) : msgSender_(msgSender) { assert(msgSender); } void PowerManager::SignalShutdown() { assert(msgSender_); msgSender_->sendMsg("shutdown()"); } This is actually better than guarding the NULL, because it makes it very clear that the function should never be called ...


75

The problem with measurements, no matter how well intended they are, is the very act of measuring the item makes it important, and the corollary, the act of not measuring an item makes it unimportant. It is absolutely essential to measure what is important, and not measure what is unimportant. Measuring SLOC (Which is effectively what your reviews are ...


73

It is indeed a good practice to keep your variable's scope small. However, introducing anonymous blocks into large methods only solves half the problem: the scope of the variables shrinks, but the method (slightly) grows! The solution is obvious: what you wanted to do in an anonymous block, you should be doing in a method. The method gets its own block and ...


68

People overlook the real purpose of a coding standards document, which is to settle disputes. Most of the decisions in the coding standard will have only a very minor effect on readability and productivity. Especially if you adopt the 'normal' style for the language, and language designers are starting to realise that this should be part of the spec (e.g. ...


68

Sure there is a good reason to name it more explicitly. It's not primarily be the method definition that should be self-explanatory, but the method use. And while findById(string id) and find(string id) are both self-explanatory, there is a huge difference between findById("BOB") and find("BOB"). In the former case you know that the random literal is, in ...


67

Some people like it your way and other people don't. Either way someone is going to be annoyed. It is just your turn this time. Suck it up and get on with the job.


66

It depends on the 'contract': If PowerManager MUST have a valid IMsgSender, never check for null, let it die sooner. If on the other hand, it MAY have a IMsgSender, then you need to check every time you use, as simple as that. Final comment about the story of the junior programmer, the problem is actually the lack of testing procedures.


61

Zipf's Law You yourself can observe by looking at this very text that word length and frequency of usage are, in general, inversely related. Words that are used very frequently, like it, a, but, you, and and are very short, while words that are used less often like observe, comprehension, and verbosity are longer. This observed relationship between frequency ...


61

Win32 is the customary name for the Windows API. This API specifies how applications can interface with the operating system. It is roughly comparable with the POSIX standard on Unix, but Win32 also covers GUIs and many other features. The Win32 API is not limited to 32-bit Windows installations. From the Windows Dev Center: The Windows application ...


60

Coding standards are not just about the favored parameters for indent -- they also include naming conventions, commenting conventions, and a large number of possible recommendations for idioms, language feature use, etc. More to the point, you still need to document all this somewhere. And finally, not everyone will want to use an IDE that reformats code ...


59

While probably not the original reason for the 80 character limit, a reason that it was accepted widely is simply reading ergonomics: If lines are too short, text becomes hard to read because you must constantly jump from one line to the next while reading. If lines are too long, the line jumping becomes too hard because you "lose the line" while ...


58

Congratulations, you've discovered objects. The reason not to do this is called the principle of least astonishment. Being surprised by a design is not a good thing. There is nothing wrong with bundling together this information but why would you want to hide it in a Bool? Put it in something you'd expect to have all this info. Bool included.


55

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


50

Short answer: We don't. Both examples are absolutely fine. There are three reasons why people use temporary variables anyway (like in your first example): It gives an explicit name to the intermediate value (we now know that it's a message, not just any old string). It helps prevent statements getting too long and too complex. It makes step-debugging ...


49

To a degree, I stopped taking this quote seriously at "Tabs are 8 characters". The whole point of tabulators is that they are not a fixed number of characters (if anything, a tab is one character). What a load of tosh. Similarly, I'm not completely convinced that setting a hard-and-fast rule of "three levels of indentation" is sane (as much as setting a hard-...


48

No, you don't need them, and I consider it an anti-pattern to automatically make interfaces for every class reference. There is a real cost to making Foo/FooImpl for everything. The IDE may create the interface/implementation for free, but when you're navigating code, you have the extra cognitive load from F3/F12 on foo.doSomething() taking you to the ...


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