259

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


116

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


93

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


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


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


69

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


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.


62

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

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.


53

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


50

It's always easy to link Fowler. One of the main examples that go against SESE are guard clauses: Replace Nested Conditional with Guard Clauses Use Guard Clauses for all the special cases double getPayAmount() { double result; if (_isDead) result = deadAmount(); else { if (_isSeparated) result = separatedAmount(); else { ...


49

I normally follow the most commonly used style guidelines or a certain coding standard tools. The advantage of using a commonly used style brings benefits when you are reading other people's code or involved in a open source project where a style guidelines are set. The most common styles that I have seen is the second style in the question. See the below ...


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

The deeper pattern is that we naturally use "[thing that varies] [comparison] [thing that does not vary]" as the standard order. This principle holds true for your example because position may vary, while size will not. The only common exception is when testing for equality some programmers train themselves to use the opposite order (known as Yoda ...


46

I like this question. The following is from my head but I think it fits quite well. status is used to describe an outcome of an operation (e.g. success/fail). state is used to describe a stage in a process (e.g. pending/dispatched). I also like this definition: status is a final (resulting) state. It is quite clear when applied to programming. Much less ...


45

Software Engineering Answer: This is just one of the many cases where simply counting beans that are simple to count will make you do the wrong thing. Its not a complex function, don't change it. Cyclomatic Complexity is merely a guide to complexity, and you are using it poorly if you change this function based on it. Its simple, its readable, its ...


45

Learn refactoring - the art of gradually improving code. We all learn all the time, so it is very common to realize that the code you have written yourself could be written in a better way. But you should be able to transform the existing code to apply these improvements without having to start from scratch.


43

I think function naming is very important here. A heavily dissected function can be very self-documenting. If each logical process within a function is split out into its own function, with minimal internal logic, then the behavior of each statement can be reasoned out by the names of the functions and the parameters they take. Of course, there is a ...


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