Adopting C programming conventions

4/28/2011 2:55 AM EDT

I forgot to mention ASTYLE. The code formatting is not an issue since we use this tool. It Works grate from and it's freeware. We run it automatically from the makefile before every build.

4/28/2011 11:14 AM EDT

The Joint-Strike-Fighter-C-Coding-Standards are available direct from the source without paying a fee to Scribd. www.jsf.mil/downloads/down_documentation.htm

4/28/2011 2:06 PM EDT

Another style guide worth looking at is google's:

http://code.google.com/p/google-styleguide/

5/5/2011 12:00 AM EDT

Absolutely correct.

I spend a lot of time working in the Linux kernel where lots of include files are pulled in and that does not seem to really hurt build time.

If the number of include files is denting your productivity then have a serious look at your dev tools.

5/5/2011 8:39 AM EDT

It's not a question of the *number* of include files; it's a question of whether each module is pulling in information that it really doesn't need, and thereby becoming coupled in ways it doesn't need to be. If someone is going to use one big include list of all include files, why not similarly just code one module with all of the subroutines in it? After all, one source file should be easier to deal with than dozens of little source files! (Heck, I started with decks of punched cards.) That's not considered good practice any more; we segment code and decompose functionality. The same should apply to data and definitions. It keeps the scope of comprehension more manageable in a person's head, which is much more important than in the compiler.

5/5/2011 3:56 PM EDT

Well said.

5/5/2011 3:55 PM EDT

If you have large teams in parallel development environments (i.e. Clear case) and your project is large, pulling in unnecessary includes can significantly impact productivity over time.

5/5/2011 3:50 PM EDT

I agree. A master include is horrible software engineering practice and can be considered 'lazy' IMO. I know first hand this is a violation of modular coding standards at large tech companies.

5/3/2011 4:17 PM EDT

Just an aside, the place I was at was mentoring some of the student engineers in K&R C. It was so funny I almost left the room laughing. I had practiced engineering for about 8 years and had not even learned K&R C. The sad thing is, what if they were hired right away, coding K&R C right now.

4/28/2011 7:16 AM EDT

There are many reasons not to use a single "master" include file. It's okay to have a common include file for basic functionality that should always be available, such as including stdint.h, perhaps microcontroller-specific includes, and system configuration - every file needs these available.

But outside that, you include the header for a module if you use that module - you don't pollute your namespace with useless names. It keeps your code clearer, easier to maintain, and more modular, and makes compilation faster.

12/19/2011 3:39 PM EST

If you import all libraries into a module, you can't tell where your dependencies lie just by looking. It goes against the spirit of information hiding. You are also assuming that all function names in all libraries are mutually exclusive, which may not be true.

4/28/2011 2:04 PM EDT

I agree that spaces in filenames and directory names are a daft idea. But so is limiting names to 8.3 letters, all capitals. Use sensible, meaningful names for files and directories, as long or as short as makes sense - just like for variables.

As to all-caps for things like define'd macros or enum constants - yes, it's a convention. And that convention stretches back to K&R's original habits. But that doesn't make it any less a poor convention - writing in all caps is ugly and distracting, and provides no benefits to coding. Some people think it's a good idea because it makes it clear that you are using a macro - but /why/ is that useful? Why should it matter if a "function" is a real function, or a function-like macro? Why should it matter if an identifier is a macro or a variable? If it makes a significant difference to the code you are writing, then you would already know the answer.

And if you really want to be able to see at a glance which identifiers are macros, then join the 21st century and get an editor with syntax highlighting.

Conventions using all-caps are from the dark ages, when C was created with the single aim of letting K&R write operating system code using fewer keypresses than writing it in assembly (their motivation for developing C was their hatred for the DEC keyboards they had).

4/29/2011 3:18 AM EDT

I've seen worse program organisation. I once had to maintain a program where there was /only/ a master include file - no other headers at all. Every extern declaration of data or functions was inside this file, in no particular order or relation to the module that defined it.

Other joys of this program included filenames in DOS convention (the compiler was DOS-based, so that's fair enough) but with a program name prefix first "PRG_". This left 4 letters unique to each file name. The programmer had the same attitude to variable and function names - none longer than 8 letters. On the very rare occasions when anything was commented, the comments were also abbreviated.

4/29/2011 11:51 AM EDT

I think I worked with the same contractor on a project.

This clown used this convention not just for globals but for automatic variables within function as well. I think this was a deliberate attempt to make the code harder to understand and maintain which in turn would help keep him employed. Here is an actual code fragment from his work.

What is really sad is this could have been replaced with a simple memcpy() function call.

void nvDefVfl(void)
{
unsigned int dvfint;// gp
far unsigned char * dvfdfptr;// flagbits
far unsigned char * dvfdsptr;// flagbits

for (dvfint = nvFdsPtr.size, dvfdsptr = nvFdvPtr.origin, dvfdfptr = nvFdsPtr.inistruc
; dvfint !=0
; dvfint--,dvfdfptr++,dvfdsptr++)
*dvfdsptr = *dvfdfptr ;
nvFdvPtr.insafter = 0 ;// insert required
}

Syntactically I had to replace pointer notation with struct notation because this site won't permit certain characters in comments. Hope the formatting of the code fragment doesn't get munched in my posting.

Don't get me started on the hungarian naming convention on steriods. Not only did the variable names include the data type but also where it was stored (EEPROM, FLASH, Local Processor RAM, External RAM etc). This led to delightful variable type definitions names like FUCBYTE (far unsinged char_byte)

He was also a huge proponent of the giant Globals.c that contained every single global variable used in the project. That way everybody had full visibility into everybody elses variables.

4/29/2011 11:52 AM EDT

Well as I feared all the white space got removed from my post. Sorry for the mashup, what I posted didn't look like that.

5/5/2011 12:07 AM EDT

It probably looks better...

I'd demand that anyone writing code like that get fired.

Hungarian really breaks a very valuable practice called Abstract Data Typing (ADTs). If you have to change the type of a variable during development - what then? You have to go edit all the code.

4/30/2011 3:15 PM EDT

Unnecessary globals are a bad idea. But the variables here may be file statics, which is normally perfectly reasonable. You've got to have your data /somewhere/.

As to whether it is better to have separate variables, or put them in a structure, that depends on the program, the target processor, and the compiler - you can't make generalisations here.


Of course, you are correct about idiotic comments. I don't see a need for any comments in that code sample.

4/29/2011 1:09 PM EDT

Until someone changes a variable's meaning, but DOESN'T change the name (especially the prefix) because that would involve changing text all over the place . . . No thanks. Turn on the compiler checking (and if possible promote warnings to errors), and use a static analyzer, and make the names meaningful instead. "Words have meaning, and names have power."

5/7/2011 6:22 PM EDT

Why not to use some print to PDF tool? If you prefer PDF, then it should be in your "most handy tools" list :)

For my self I use One Note for such articles, as this allows convenient article archiving and "global search", even in pictures or figures.