C: What is a good source to teach standard/basic code conventions to someone newly learning the language?

Question

I'm tutoring someone who can be described as a rank newcomer in C. Understandably, she does not know much about coding conventions generally practiced, and hence all her programs tend to use single letter vars, mismatched spacing/indentation and the like, making it very difficult to read/debug her endeavors.

My question is, is there a link/set of guidelines and examples which she can use for adopting basic code conventions ? It should not be too arcane as to scare her off, yet inclusive enough to have the basics covered (so that no one woulc wince looking at the code).

Any suggestions ?

Answer 1

I would recommend the book Clean Code. It describes several coding best practices, including things such as code structure, comments and variable naming.

Answer 2

Code Complete is a good reference. Not just a list of rules, it provides reasons behind doing things one way or the other.

Answer 3

There's lots of resources that say "this is how to write good clean code that is easy to read". The more important part of this is the "why" of it all. Really learning the "why" usually seems to involve some personal suffering with bad code.

My first big learning experience on this came during a college co-op position, in being assigned to document a communication system code in C. This was a central message passing servicer between other processes. Very few comments were present at all, and those few that were there were wrong, the structure of this code was copied from elsewhere and they forgot to remove some of the old comments... There were some reasonable names for things, but it was a nightmare to figure out. Make her reverse-engineer and document some crap code.

I've always done better with indentation, I guess that got through to me easier in class. I've seen some horrible code here at work where indentation seems to be produced by a random number generator on each line. Absolutely horrible. First thing I do is go through and try to get indentation to make sense before I look at what the code does. Make her figure out some crap code.

Really, I think it's best to turn your experience around and show her what it's like to be the one trying to understand what there is to see. After all, in the real world, her future self is likely the main person she needs to document for. Show her some of her previous code from a while back and have her figure it out and explain it to you.

Then show her some good code, have her figure out and explain what ti does, and have her see how much easier that is to deal with.

Answer 4

I think Clean Code and Code Complete is not suitable to her current stage. I suggest you direct her to read The C Programming Language and write the function samples in her own way and let her compare her own implementation with the book. This will improve her programming ability a lot. After finishing this book, Clean Code and Code Complete maybe the best choice for her.

Answer 5

I'm a big fan of Bruce Eckel's "Thinking in ..." books, but he hasn't written one specifically for C (though I highly recommend "Thinking in C++"). He does have a link on his site to a web seminar titled "Thinking in C" which might be a place to start (at least worth a look as it's free).

Answer 6

There are 2 main reasons to use a specific indentation style:

a) It is better readable (objectively)
b) It is, if you're re used to this style. It may be a different style, but a style, which is consistent over a project.

Part I means, not to glue everything together:

int x=l*(1-i)-k(9);
int x = l * (1 - i) - k (9);

To know where you're will find the closing bracket for a opening one, and vice versa, without decorating your code with

} // end if

and where the code, belonging to that bracket, is indented.

IMHO, for C, there are two big schools: K&R and Allman-Style. The main difference is:

KAndR (void) {
    Allman ();
}

Allman (void) 
{
    KAndR ();
}

It is needed for fast orientation, not for looking nice.

There is, escpecially for C-programs, the program gnu-indent, which can be configured to indent in different styles. Ask her to use it before submitting something to you, or else do it yourself. Eclipse has such a thing built in for Java-code. I would reject improper formatted code. That she profits at most from proper code is something she should learn fast, if she is reusing her own, unformatted code.

Some Conventions are just conventions, and useful if followed by the whole community. For example a constant needn't be named by capitals, but if I read MAXAGE, and can rely on the thesis, it is a const, I save much time, compared with searching.

Variable names are harder to get right. But as a rule of thumb: For loop-counters, i and n are perfect. Most other values should carry meaningful names.

Answer 7

When learning anything, I think a wide variety of activities and paradigms are needed. You will soon get past the indentation and formatting issues, and can embark on a deeper level of training that will be more interesting to both of you.

I think it is cool sometimes to borrow from other areas of endeavor (like sports or classical music) where the kind of coaching and mentoring you describe are extremely common, as opposed to our own field where it is either one extreme or the other (self-taught vs. taught to the syllabus/tests as sometimes happens at universities).

Kindergartens and public elementary school education was designed with the idea that several subjects need to be taught: reading, writing, penmanship, history, math, civics, physical education. As your mentoring progresses, to play with the analogy a little, I think you need a portfolio of topics that goes beyond programming languages (writing) and coding standards / coding conventions (penmanship). Many kids burn out on music in a hurry because playing scales and goofy little exercises don't click with them.

A very famous music teacher, Dorthy Delay had hundreds or thousands of students, including some of the most famous musicians in the world, during her long career at Julliard. She had a program for her students that included five hours per day of individual practice. Added onto class work and performing with ensembles (think working in teams), she required a heavy workload. And so should you.

The following chart summarizes what she recommended / required:

http://gallagherclarinets.blogspot.com/2012/01/dorothy-delays-practice-mindmap.html

Having had some musical training when I was younger, I'll try to translate the analogy.

• Exercises - API Tutorials: Find a programming feature you haven't done and learn to do it. Another parallel might be scripting and writing small programs to increase fluency in a programming language.
• Scales - Refactoring: Take a piece of code and smooth it out to eliminate code smells. Scales are considered important because they help musicians focus on playing in tune and on moving their fingers efficiently so they can play faster. Perhaps this could also correspond to use of valgrind, lint, static and dynamic analysis tools that look very closely at the per statement / per function aspects of programs.
• Studies - Like exercises, but bigger scope. Maybe learn a new tool or framework.
• Pieces - Applications. Pieces are like concertos or sonatas, they are what gets delivered to audiences / customers and required iterative / incremental improvements that may span years of work.
• Other - These are not obscure references to particular lesson books or composers. Playing for fun / coding for fun line up. So does listening to music / reading other people's code. Mental rehearsal refers to running through a memorized musical piece in your head. For developers this role might be taken my thinking about an app, note taking or sketching on paper or a white board separate from the work of coding or documenting formally.

If we take the musician analogy further, try to make opportunities for your protege to pair program with you and others, and to work in small, medium, and large teams, particularly those that perform frequently.