Commonly Accepted Best Practices in Programming

The art of programming, or the practice of software engineering, is a rapidly growing field where new knowledge is outdated weeks or sometimes days after that knowledge emerges. This type of environment has left much to desire in the way of the idea of "the right way to do things". Rather than adhere to government regulations, mathematical laws, and codified best practices like most engineering fields, a programmer only needs to ensure that their program produces acceptable output. No matter how ugly, disturbing, painful, or time intensive a program is, if the right numbers and letters are spit out at the end, people are happy.

What then separates a 'good programmer' from a 'bad programmer'? The use of best practices as accepted by the community as a whole is often the bar for quality measurement of a programmer and his/her work. In the end, a program that produces accurate output is the goal, but the journey is just as important as the destination. Producing code that is free of vulnerabilities, easy to read and reuse, and well documented is just as important. A common trait of a 'good programmer' is constantly working to hone his/her craft and learning more about his/her work.

The following is a list of commonly accepted best practices (CABP) and an overview of the concepts.

CABP 1: Document Your Code!

Many programmers have had the unpleasant experience of looking at another person's code, or even their own code, and wondering what in the hell the writer was thinking when they wrote that!? If you are a programmer that has not managed to experience this, you are either an omniscient programming demigod or, more likely, you work with code that is well documented. Documentation doesn't have to be pages of boring technical specifications and mathematical formulas (although it can be; this is better than nothing), it can be as simple as a comment block at the beginning of a function or using verbose variable names.

Self documenting code is a popular choice because it requires less special effort on the part of the programmer. 'int NumberOfChickensAvailable;' makes a lot more sense than 'int c;'.

Comments and comment blocks are also very useful in writing code that makes sense. Use comment blocks at the beginning of functions to explain what the functions does at a high level and why it exists. Smaller comments can be used to help document smaller blocks of code. Use comments to explain the reason you are doing something a particular way, not just what a code block does.

Writing out descriptive and accurate APIs will make your users love you. APIs are not always needed in every program, however if you ever work in an object oriented environment they are invaluable.

This CABP is closely related to the CABP 2: Use Consistent Formatting and Naming Conventions.

CABP 2: Use Consistent Formatting and Naming Conventions

Correctly using whitespace and tabs increase the readability of code. There is not a single formatting convention that is best, it is more important to be consistent than to be 'right'. The same goes for naming conventions for variables and functions. One common naming convention is making variables nouns and functions verb phrases (ex. int chickens; for a variable and int CountChickens() for a function).

Pick a style or create your own and then stick to it. Even if a stranger dislikes the conventions you use, if you are consistent the code will make more sense. This CABP is best used in conjunction with CABP 1: Document Your Code!

CABP 3: Avoid Repetition

Try your best to avoid repeating chunks of code and variables. If you find yourself writing out the same block of code in a program more than two or three times, consider making a function to contain that block. Avoid creating a new variable for the same piece of information in every function you make. If you use the same piece of information in many places consider passing the original variable as a parameter so that when updated it only has to update once. Another option for this situation would be to create a constant variable or even (gasp!) a global variable.

Also, avoid reinventing the wheel. There is a lot of code in the world. It is almost always better to include a library and use it to calculate trigonometric functions than to try and write sin, cos, and tan yourself. Reusing code is not a sign of bad programming and does not indicate the intelligence level of the programmer. Save yourself some time and prevent some potential bugs by reusing code that has already been found to bug-free and consistent.

CABP 4: Low Coupling and High Cohesion

Coupling has to do with how much external data or information is required of a function or object to operate. A highly coupled function or object requires the use of global variables and/or needs to know the structure of data structures in other functions or objects. If one changes any of the external data, the function will no longer function or the object will begin to object. A low coupled function or object will be able to complete its task(s) with no help from outside of itself. You pass the function a few parameters and it does it's thing.

Cohesion has to do with how simple a function is and how easily you can use it. A highly cohesive function will do one thing and one thing only and will do that one thing reliably. A function that calculates the sum of two parameters is highly cohesive. A poorly cohesive function is a function that will perform addition, subtraction, multiplication, or division based on the flag you pass in addition to the numbers in question.

A program should be low coupled and highly cohesive. This allows each function in the program to do its one job without relying on anything else. Practicing low coupling and high cohesion will also lead to less complex code and makes that code reusable as a bonus.

CABP 5: Keep it Simple, Stupid

Do not write overly-complex code. Counting the number of chickens in a pen should not involve dividing the chickens into sub-species and sorting them by last name. Just count the chickens. Do not add extra functionality to a program or function just because it could be useful. A tool box full of tools is more useful than a Swiss army knife with the same tools in most situations. Bells and whistles are just that, bells and whistles. Unless it increases the usability of your program, just don't do it.

Write functions that do one thing and do it well (See CABP 4: Low Coupling and High Cohesion) and this will simplify your code immensely. Keeping your code simple will help you dig out bugs faster and avoid bugs altogether!

This CABP is also highly related to CABP 3: Avoid Repetition.

CABP 6: Test Your Code

After you write that perfect program that does exactly what you had always dreamed, you test it out. That sounds like a no-brainer, right? Oh, there was one little typo in the code. *click click click* All done! Right? Wrong. You didn't test your code again. Test everything and test often. Running a few more tests than you think is necessary is always a good thing. Keep in mind the scope of what you are doing, of course. There is little need to test for an integer overflow on a little calorie counter app you wrote for personal use (you probably should test for it anyway); however if you release that same calorie counter on the Google Play Store, you should probably test for integer overflows because there is always some prick out there who will enter 1 Googol calories for that apple just because they can.

Bottom line is, test your code and test it often to prevent your code from crashing or exposing a security vulnerability.

CABP 7: Sign Your Code

Be proud of your work. If you ever write something and feel ashamed to put your name on it, you should probably rewrite that code. Use your signature as a stamp of approval and care about your work. Above all else, as a programmer you should enjoy programming.