Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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 ?

share|improve this question

closed as off-topic by Thomas Owens Aug 24 '13 at 15:55

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – Thomas Owens
If this question can be reworded to fit the rules in the help center, please edit the question.

1  
What code examples are they reading? Where are they supposed to learn style from, if not from reading other code? –  S.Lott Jun 29 '11 at 17:42
    
Since you're tutoring, it seems that you'd be the perfect resource. Explain meaningful variable names and why they're important, code format consistency and why it's important, and any other conventions that seem appropriate. If you suggest conventions that are actually useful, there should be no reason for her to be scared. It's better to learn from someone you respect and trust than from a stranger's book or blog. –  Corbin March Jun 29 '11 at 17:58
    
@Corbin -Yeah, she would listen to me - but she's a skeptical person (logically, not personally !!), so I'd need to convince her that what I'm saying is also what is the "accepted" norm, rather than my own preference (since almost no 2 programmers have 100% same coding styles !!)... –  TCSGrad Jun 29 '11 at 18:12
    
@S.Lott- She's still going through the "sum of multiples of numbers" phase - i.e learning to put logic into code, so any code more than 25-50 lines may be lost on her... I don't want to go too fast too soon, and make programming look scary/boring (instead of the fun it is!! ) –  TCSGrad Jun 29 '11 at 18:13
    
They're not reading code examples? How can they learn to code without reading code? How can you teach a style without showing code examples in the style you want? How is that going to work? Please explain how someone learns a style without reading code in that style? –  S.Lott Jun 29 '11 at 18:18
show 3 more comments

6 Answers

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.

share|improve this answer
    
+1 for K&R, the only great source. –  Macneil Jul 7 '11 at 14:15
2  
"After finishing this book" is a pretty bold statement with respect to K&R. There's a difference between reading the book and reading and understanding everything and solving all the exercises :) –  BlackJack Jul 7 '11 at 23:54
    
Learning C without reference to K & R is like growing up in the US without learning about George Washington. It gives insight to the languages strengths and weaknesses and how C, Bell Labs and UNIX influenced each other. Artifacts that give homage to DEC PDP hardware (logical/bitwise/shift/pre-post increment operations), filter programs, augmented structured programming with break and continue combined with versatile for, while and do while statements, and things like MACROs belong to a transitional/pivotal time in programming languages that allowed C to compete and prevail for a long time. –  DeveloperDon Sep 3 '12 at 19:33
    
To clarify, I am not saying C is the greatest (or worst) language. It has staying power and for good and evil, had strong influence on languages that followed like C++ and objective C, perhaps with lesser effects on C# and Java. Both C and K & R are historically important enough most developers should know them to some degree. –  DeveloperDon Sep 3 '12 at 19:38
add comment

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

share|improve this answer
    
Just curious, does it use a specific language in examples, or is it language agnostic? What about paradigm like imperative, OOP, functional, etc. –  Karl Bielefeldt Jun 30 '11 at 2:59
1  
@Karl Bielefeldt: It uses Java, but the advice is language agnostic in general. Some of the advice is OOP specific, but much of it is applicable to imperative programming and C. –  Anto Jun 30 '11 at 9:32
    
would you mind explaining more on what it does and why do you recommend it as answering the question asked? "Link-only answers" are not quite welcome at Stack Exchange –  gnat Aug 24 '13 at 16:07
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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).

share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.