A compilation of best programming practices ?

[Timst]

Hello !

So I keep hearing a lot of good pieces of advice from teachers, fellow developers and various other sources. Advice about how static members / methods should be avoided at all cost, how goto/break are the devil incarnate, how global variables are the leading cause of cancer in children, that sort of things.

Now, most of the time it makes sense, and good teachers / fellow developers / whatever will even provides an explanation and a workaround. The problem is, you have no way of knowing whether a particular technique is recommended or the absolute evil unless *someone* warn you about it. So my question is : is there some kind of website / e-book / wiki that list all the best programming practice ? I know this is heavily influenced by the language used (it will also be nice to have tips categorized by language), but I guess there is a bunch of patterns that apply on every implementation, and it will be nice to have a centralized place to learn about them.

[sakekasi]

I'm not sure this is exactly what you want but for java, effective java by joshua bloch is quite a good book for many good java coding practices. I guess some of this applies to object oriented languages in general.

[Sc4Freak]

Advice about how static members / methods should be avoided at all cost

how goto/break are the devil incarnate

In a language like Java/C#, methods should be static unless otherwise necessary. If you don't need an instance to call a function, then making the method static limits the amount of useless information the method has access to (information hiding). The equivalent in C++ are free functions vs. member functions: in general you should prefer free functions over member functions if you have a choice.

There's absolutely nothing wrong with break either. There are certainly cases where using a while(true) with a break somewhere in the body leads to more readable code, for example. And even goto has limited but legitimate uses. Goto generally shouldn't be used in C++, but a legitimate use in C is to use goto to jump to the end of your function to clean up resources in the event of an error.

Rules which say "never do X" or "don't ever use Y" are silly. Language features are tools, and there are cases where they should and shouldn't be used. Even "devil-incarnate" features like goto have legitimate uses. The important thing is to learn where they are and are not applicable, because blanket statements like "never use goto" don't work.

[Berengal]

Best" practices are harmful. I've seen more damage done by "best" practices than by the things they're supposed to keep you from doing.

There are no hard and fast rules on how to write good code, only aesthetic principles, and those are very hard to teach and impossible to condense into a single sentence.

Be especially aware of don'ts, and also be aware of interpreting dos as don'ts. Do "write short methods", don't "don't write long methods". Do "give your variables good names", don't "don't give your variables one-letter names". Above all, never take a rule for granted, and don't even bother remembering it if you cannot get a good "why" that you know is true (not suspect, not believe, not that you think sounds reasonable).

[_Axle_]

Mostly what Berengal said.

Follow the style/flow of whatever project you are working on as well. The only "Do Not" I would say, which I would say 95% of other Programmers/Comp Sci people would agree . . . Do not use goto statements, unless that is the language's only good way to do branching.


Note, previous percent was randomly made up on the spot, I have no citation or source

[Mat]

If I'm unsure whether something I wrote is good or bad, I ask myself if it is making life better or worse for the people who will have to work with/maintain it. This is very much tied to aesthetics, and also depends on the established coding style of the project. However I think there are still some general principles which are pretty universal, e.g. the idea "don't repeat yourself" or that functions/classes/modules etc. should have a clear focus and be well named.

The short methods/long methods is a great example of a piece of advice that is absolutely useless without knowing the reasoning behind it. When is too long? What do you instead? When are the exceptions? To me this is all about abstraction and deciding what details are necessary to understand what the function or method does. There is no right length that applies to everything.

[tipo test]

You may like to know what to not do:

http://freeworld.thc.org/root/phun/unmaintain.html
http://en.wikipedia.org/wiki/Anti-patte ... i-patterns

[ochuckles]

My coding aesthetics:
Try to describe all the patterns.
Don't describe patterns that aren't there.

Keep in mind that phrases like "best practice" and "industry standard" often exist to absolve people of guilt and responsibility when projects fail. Programmers of all people should know that there is no algorithmic assembly-line process for shipping good software. No simple one anyway. Don't let them fool you.

A lot of professional programming culture is based on 1) the fact that many individual programmers don't want to be responsible for the success or failure of the product and 2) that most professional programmers are primarily concerned with job security and only secondarily concerned with doing anything well.

I guess you just have to ask yourself what your priorities are...

[Yakk]

There's absolutely nothing wrong with break either. There are certainly cases where using a while(true) with a break somewhere in the body leads to more readable code, for example. And even goto has limited but legitimate uses. Goto generally shouldn't be used in C++, but a legitimate use in C is to use goto to jump to the end of your function to clean up resources in the event of an error.

"Goto considered harmful", to me, is the thought that languages should be developed in ways to remove the need to do Gotos.

In machine languages, even function calls are gotos. You develop your assembly language to give you access to abstractions (like labeled function calls), and then to C style function calls and if/else/while/break/continue/for structures with C. C++ adds in things like RAII, try/catch blocks, and other attempts to do away with goto. Each time a "layer of goto" is hidden from the programmer and turned into a pattern with language support.

The same goes for macros: macros where found to be problematic in C, so people started adding features to C++ and other related languages to do away with the need for macros in the cases where they where useful.

If you are using gotos/macros, check to see if your language offers an alternative for this case. Minimize their use, as often there have been really beautiful structures built up to replace exactly that use. And in other cases, it might not be worth it anyway.

Now this isn't always the case: C++03 doesn't have a replacement for the file/line macros from C as far as I know (which can be ridiculously useful when debugging and otherwise analyzing code). If I remember rightly, some stuff slipped into C++0x along those lines (however, you'll notice that macro support has been increased even in C++0x.)

[Markus__1]

An answer that goes in a completely different direction:

Look into the documentation of static checkers for your language (if there are any).

See http://en.wikipedia.org/wiki/Static_program_analysis and the list of tools linked from there.

While a lot of rules are language-specific, there are also some that are more generally applicable, and the documentation of each rule often has a short rationale for it. See e.g. for Java http://pmd.sourceforge.net/rules/design.html .

[MHD]

This is from my signature (in case I change it in the near future...)

Code: Select all

Good Code                                                                                            Fun Code
Readable, Understandable, Maintainable, Self-Explanatory, Idiomatic, Efficient, Optimized, Elegant, Hackvalue

It's a thing I developed and posted in this thread.

And I usually stick to it. It is not as much a "Best Practices" as it is a sliding scale. Look at your code from time to time and think "Where on the scale am I?"

[RogerB]

I suspect I'm not quite answering the original question as this is about best software engineering practice, not best programming practice but I I think that Steve McConnell's "Code Complete" is worth a mention.

[RoadieRich]

The C++ FAQ is a pretty good resource for this.

Is even goes as far as explaining that even if something is what it calls evil, there are still times when it might be a suitable option.

[cogman]

First, for every hard and fast "you should never/alway do X" there is some exception which invalidates that rule.
Next, Every programming language has its merit and no programming language is perfect. Take with a grain of salt the opinion of people who can't find fault with a language or people that can't see any benefits of a language.
In the same lines, take programming paradigms and fads with a grain of salt. Agile isn't for everything. OO won't cure the world, Functional programming isn't for every situation.
Learning more about WHY things do the things they do is never a bad thing. Learning assembly or memory management won't hurt you.
Documentation is great when it is accurate and a stumbling block when it is not. When you update your code, make sure you update your documentation (where needed).
Everyone starts somewhere, don't be intimidated by how far behind you may be from someone.
Everyone starts somewhere, don't insult or talk down to people who you think are not on your level.
If someone tells you that your code sucks, they aren't saying "You suck and I hate you!" they are saying "Your code sucks and can be improved". Don't take criticisms of your code personally.
Some people criticize any code that isn't written the way they would write it. You shouldn't always ignore what they say, but just realize that they aren't always right when they criticize your code.
The art of programming is one where you learn by doing, copying code that you didn't write will NOT teach you programming. Reading others code is invaluable, copying is detrimental.
Don't give up. Great things are accomplished by average people that don't give up.

[EvanED]

So I have some comments on this post... but don't take it as disagreement per se. More like... elaboration.

First, for every hard and fast "you should never/alway do X" there is some exception which invalidates that rule.

At the same time, keep in mind that they are supposed to be exceptions; have a good reason for violating them. The more or worse the consequences of violations, the better your reason needs to be.

Next, Every programming language has its merit and no programming language is perfect. Take with a grain of salt the opinion of people who can't find fault with a language or people that can't see any benefits of a language.
In the same lines, take programming paradigms and fads with a grain of salt. Agile isn't for everything. OO won't cure the world, Functional programming isn't for every situation.

Also beware orthodoxy. Not everything needs to be written in C for teh sp33dz.

Learning more about WHY things do the things they do is never a bad thing. Learning assembly or memory management won't hurt you.

In fact, learning what's going on under the hood will almost certainly help; perhaps a great deal.

The art of programming is one where you learn by doing, copying code that you didn't write will NOT teach you programming. Reading others code is invaluable, copying is detrimental.

At the same time, you should learn from examples, and you shouldn't reinvent the wheel if someone else did it for you (or you are explicitly trying to learn how to make a wheel). Just understand the code before you slip it into your project.

[cogman]

...

The art of programming is one where you learn by doing, copying code that you didn't write will NOT teach you programming. Reading others code is invaluable, copying is detrimental.

At the same time, you should learn from examples, and you shouldn't reinvent the wheel if someone else did it for you (or you are explicitly trying to learn how to make a wheel). Just understand the code before you slip it into your project.

Well, Idk, reinventing the wheel is a great way to learn how to make different wheels.

If you just want to finish a project, then yes, reinventing the wheel is pointless. If you want to learn how to do something, then just using what someone else has already done won't teach you how to write the thing yourself.

For example, at least in my school, one of the most popular exercises was implementing the different sorts (quick, selection, heap, merge). Now, have these sorts been implemented, optimized, and improved to death? Yes. But was rewriting them a good programming exercise? Yes. Would I use the sort I wrote in production code? Probably not. The only exception is if you actually do do things better (pretty hard to do for common algorithms).

[sourmìlk]

...

The art of programming is one where you learn by doing, copying code that you didn't write will NOT teach you programming. Reading others code is invaluable, copying is detrimental.

At the same time, you should learn from examples, and you shouldn't reinvent the wheel if someone else did it for you (or you are explicitly trying to learn how to make a wheel). Just understand the code before you slip it into your project.

Well, Idk, reinventing the wheel is a great way to learn how to make different wheels.

More importantly, reinventing the wheel is useful when you can't get the god damn old piece of shit wheel to work. That's my problem with .NET: you have to use the old wheel and the old wheel sucks.

[akashra]

I have but one rule about 'Best practice[s]': That if you use the phrase in a job interview I'm conducting, you will not get the job.
It's basically an arrogant way of saying "I do things this way, therefore you should too".