Coding Standards

1. Coding Standards CISC370 - Fischer

2. Coding Standards • This is just how we, as humans, format our computer code. • The computer does not care at all about this. How you format your code will not (directly) effect how your programs runs, at all. • However, programming ( in practice ) is a team sports. Coding conventions can help the team work together better. • So why are these important? Why might it be bad?

3. The Good Common standards a few good things happen: • Programmers can go into any code and figure out what's going on. • New people can get up to speed quickly. • People new to C++ are spared the need to develop a personal style and defend it to the death. • People new to C++ are spared making the same mistakes over and over again. • People tend to make fewer mistakes in consistent environments.

4. The Bad You’ll hear lots of reasons why coding standards are bad / pointless. Some of the reasons are even almost valid. You may hear • The standard is usually stupid because it was made by someone who doesn't understand C++. • The standard is usually stupid because it's not what I do. • Standards reduce creativity. • Standards are unnecessary as long as people are consistent. • Standards enforce too much structure. • People ignore standards anyway.

5. Project Engineering 101 • Software Engineering is an extraordinarily expensive undertaking. • Because of this, it usually requires the code to stay around for a while - How long did Microsoft have to maintain/patch/(defend in court) Windows 95?

6. Project Engineering 101 • Turnover rate is also very high for Software Engineers – by some estimate as high as 30%. • So, even at a good company with a low turnover rate, say, 15%, with 100 software engineers, that’s 15 people that need to get up to speed on a project – and 15 people that took all their knowledge about what they coded with them.

7. Project Engineering 101 • Also note that for the maintenance phase of a project can run 50-80% of the total engineering effort. • So it’s very important for new programmers to be able to get up to speed in a relatively short amount of time.

8. What you can do • There are a lot of things you can do, as a programmer, to make it easier for others to understand your code (we just saw why this is important.) • Specifically, there are things you SHOULDN’T DO. Although lots of programmers do them.

9. What you can do • I’m going to show you examples of these. • Keep in mind, a lot of these examples are (purposely) a bit over the top. • I’m going to show you these examples from the point of view of someone who’s TRYING to make his code unusable by anyone else. • Don’t let this distract you from the real point, these are things not to do – and seeing people do this can make you understand why.

10. Single Letter/Very Short variable names • By naming your variables a,b,c, etc., not only will no one know what they are, it also makes it impossible to search for them with a text editor. • Two letter variable names are also almost as useless.

11. Naming • In naming functions and variables, use abstract words like it, everything, data, handle, stuff, do, routine, perform and the digits e.g. routineX48, PerformDataFunction, DoIt, HandleStuff and do_args_method.

12. CapiTaliSaTion • Randomly capitalize the first letter of a syllable in the middle of a word. For example: ComputeRasterHistoGram().

13. Names from Mathematics • Choose variable names that masquerade as mathematical operators, e.g.: openParen = (slash + asterix )/ equals;

14. Bedazzling Names • Choose variable names with irrelevant emotional connotation. e.g.: Marypoppins = ( superman + starship ) / god; This really confuses the reader because they have difficulty disassociating the emotional connotations of the words from the logic they're trying to think about.

15. Uppercase l looks a lot like the number 1 • Use lower case l to indicate long constants. e.g. 10l is more likely to be mistaken for 101 that 10L is.

16. Masquerading Techniques Include sections of code that is commented out but at first glance does not appear to be. for (j=0; j<array_len; j+ =8 ){ total += array[j+0]; total += array[j+1]; total += array[j+2]; /* Main body of total += array[j+3]; * loop is unrolled total += array[j+4]; * for greater speed. total += array[j+5]; */ total += array[j+6];} Without the colour coding would you notice that three lines of code are commented out?

17. Red Herrings Pepper your code with variables that are never used and methods that are never called. This is most easily done by failing to remove code that is no longer used. You can save the code on grounds someday it may need to be revived. You get bonus points if these drone variables and methods have names similar to actual worker ones. The maintenance programmer will inevitably confuse the two. Changes made to drone code will happily compile, but have no effect.

18. Documentation Lie in the comments You don't have to actively lie, just fail to keep comments as up to date with the code. Document the obvious Pepper the code with comments like /* add 1 to i */ however, never document wooly stuff like the overall purpose of the program or function.

19. Documentation Document How Not Why Document only the details of what a program does, not what it is attempting to accomplish. That way, if there is a bug, the fixer will have no clue what the code should be doing. Avoid Documenting the "Obvious" If, for example, you were writing an airline reservation system, make sure there are at least 25 places in the code that need to be modified if you were to add another airline. Never document where they are. People who come after you have no business modifying your code without thoroughly understanding every line of it.

20. Units of measure Never document the units of measure of any variable, input, output or parameter. e.g. feet, metres, cartons. This is not so important in bean counting, but it is very important in engineering work. As a corollary, never document the units of measure of any conversion constants, or how the values were derived. It is mild cheating, but very effective, to salt the code with some incorrect units of measure in the comments. If you are feeling particularly malicious, make up your own unit of measure; name it after yourself or some obscure person and never define it. If somebody challenges you, tell them you did so that you could use integer rather than floating point arithmetic.

21. The Ugly? • We’re going to make up a coding standard for our class. Everyone in our class will use it. It’ll be posted on the website. • It’s going to be fairly simple (read: incomplete). • The whole point of this is to get you thinking about structuring/commenting your programs – not to rigidly enforce it.

22. So here it is 1) Each Source File should have a comment block at the top, with your name, the date, the program filename, and a short description in it. 2) Variables names should be self describing, exceptions being loop counters in for loops, etc. • int myWeightInPounds; int timeoutInMsec; 3) Function names should also be self describing • CheckForErrors() instead of ErrorCheck(), DumpDataToFile() instead of DataFile(). 4) Use consistent case. camelCaseIsFine 5) Indentation – always exactly 3 spaces, not tabs. 6) No magic numbers – any number other than 0 or 1 should have a constant defined for it. Example: • const int squareFeetInSquareYard = 9;

23. So here it is 7) Use spaces in all assignment statements, and always use brackets in control / repetition statements for ( int i = 0; i < someConstant; i++ ) { //do something } if ( a == b ) { //do something } This is sometimes referred to as “One True Brace”– and it should almost always be used. 8) Use meaningful comments to describe complex situations, avoid unless comments.