Tips on code layout?

This topic is too big to cover all aspects. Besides, people have different views on readability and maintenance, so it would be not very good to give two stiff requirements. More to this, you can work in a team where all members want to see neat code (it can be too hard to work with those who don't) but have different views on how to format the code, so my first advice would be my provisions I made to address this sometimes painful problem.

The key is specific to C#. For this language, Visual Studio (some alternative IDE have equivalent features) detailed auto-formatting rules are defined in the options. Use those rules. You can modify them, but keep formatting consistent. The criteria for good formatting is: if you cut all code and paste it, auto-formatting will result in exact same code formatting. Now, what to do with different team members who don't like your set of options? I put forward the following rule: the one who formatted the code for the last time is always right. Don't like formatting of your colleague? Reformat it to you taste, but only automatically. If you do any changes, commit them using your formatting; the one who use your code later can turn it to one's liking. If you don't do changes, just reading, reformat it to your liking, read all you need, but don't commit the changes. (In this paragraph, I assume you always use some Revision Control System. Don't even play with the idea of working without such system; it would mean that you are not doing programming at all, because your valuable programming assert would not belong to you, but to the first accident or just a human mistake.)

Unfortunately, auto-formatting does not cover all aspects. On of the "free" formatting features is the blank lines. I would advise to develop strict rules about them, but it's up to you.

And then, there are a lot of aspects not related to formatting. One of them is commenting. I cannot write too much about it, but it needs a lot of explanation of the ideas. So, I would leave you with just one idea: code should be self-commenting. Now, naming. I would strongly advise to use Microsoft naming convention. But this advice does not cover all aspects of naming, which is the whole art. Just develop good taste.

But the biggest problems go well beyond the formatting, naming and commenting. Most of them are in the code in general. It's very hard to advise something certain, because number of ideas is quite big, even if I counted only my own ones. This topic is to close to general code architecture and design to discuss anything seriously. But I'll list just few quick points.

Pay close attention for partial classes and putting part in different files. Sometimes I use files with identical file names, but in different directories. The files of identical names have different parts of the same classes. This way, you can separate different aspects. For example, two different files "ParsingRules.cs" in the directory "Model" and in the directory "Model.Binding". In one file in first directory you have main parts of some class(es), and in another file in another directory you have other parts of some of the same classes with methods implementing binding. And so on. Also, pay attention for anonymous methods. The are good in one cases and bad in others. All right, I am already sorry that I started to talk about the code design. Consider different alternatives and ask your questions in separate post. All topics involved in your question can make a big book. Anyway, perhaps the main advice will be: avoid hard-coded immediate constants by all means, better declare explicit constants or use resource. No "magic words", ever. Don't repeat yourself.

What is good code? Well, try to read the code with the difficult solution you developed 3 months ago, 2 years ago… Can you quickly find out how to solve the similar problem looking at your old code? If so, my congratulations. What, your colleagues started to say the same about your code? This is hard to believe, but it this is really so, it's time to make your portrait, add the words "Great Readability Master", frame it and hand in the office. Wish you the best of luck.

—SA