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.

My colleagues and I are a bunch of scientists (i.e., untrained in programming) hacking code for data processing. Is there a concise and simple reference that documents idioms, conventions, or guidelines for organizing code? For instance:

  1. conventions for using global variables
  2. documenting code that is distributed to others (e.g., at least listing all functions contained within a code document at the top of the file)

and so on?

I'm aware that this is big field and can get into security, unit testing, refactoring, and all these issues, but hopefully there is some primer out there that covers the bare minimum with (extremely) little programming experience?

Edit: Thanks all -- I aware there are language specific guidelines for (and debates over) use of parentheses, camelcasing (or not) variable names, etc. but I was hoping for basic conventions that apply to most languages.

Edit2: To narrow it down, these are mostly imperative or procedural languages (e.g., Fortran but one in particular that a lot of my colleagues use is a DSL called IGOR Pro by Wavemetrics if anyone has heard of this one).

share|improve this question

migrated from superuser.com Feb 16 '11 at 16:42

This question came from our site for computer enthusiasts and power users.

    
For any specific language or general for any language? –  rems Feb 16 '11 at 15:44
    
"2." is largely unnecessary, except if you write your code in notepad. Most modern editors can identify functions in a file. –  Daniel Beck Feb 16 '11 at 15:50
    
@rems -- hopefully for any language! –  stephen Feb 16 '11 at 16:05
    
@Daniel -- unfortunately in the field that I work in, there are a few domain-specific languages that require the use of their own (inadequate) editors... –  stephen Feb 16 '11 at 16:06
1  
@Daniel -- thanks, have you heard of IGOR Pro by Wavemetrics? This is one that I have in mind at the moment. –  stephen Feb 16 '11 at 16:14

5 Answers 5

These guidelines (coding conventions and style guides) are largely language-specific. Features and restrictions of programming languages steer guidelines regarding code organization (e.g. Java packages mirrored through the directory hierarchy, or that the source file must have the same name as the class within), entity naming, and so on.

Many programming languages (like Python with PEP-8, or the .NET Naming Guidelines by Microsoft) have certain widely accepted style guides. Use these if you can, and your code will match expectations of others used to these guidelines.

For others (and those mentioned above), there are tons of style guides and other source code organization standards, regulating barely anything (e.g. only public function naming and tab width) or pretty much everything. Many of these guidelines are specific to organizations and vary widely.


Look around the web, and use what you like. If there are widely accepted standards such as those I mentioned for your environment, adopt these. If there are automatic code checking utilities for your environment (like CheckStyle for Java, or FxCop for .NET), you can try using these.

share|improve this answer
    
I also search the net with terms like "patterns and practices", "best practices" or "guidelines" to find similar items. –  Dillie-O Feb 16 '11 at 15:52

Both Daniel and rems are on the money in that conventions are 'community-based', which is why they were asking what languages you were using.

So asking us to answer independent of language will be interesting!

I would like to refer you to the 'Holy Bible' of programmers, Code Complete by Steve McConnell. This is a classic resource and will help you refine your practices. In your case, I suggest looking at Chapters 11, 14-16, and 31-33.

Remember that although you are writing code to instruct the computer to do something, always strive to make the code's purpose clear to the next person who will read/edit it.

This includes but is not limited to:

  • Naming Conventions - variables (local, global), constants, methods/functions, classes.

  • Style Conventions - spaces vs. tabs for indentation and general code layout.


NOTE: This question might be best migrated to programmers.stackexchange.com because this is a subjective programming question.

share|improve this answer
    
Suggest that once you start writing some code, get input from other people and see if they can understand it! If not, then identify why not? See if making changes, like changing the variable name or method name helps. Eventually you and your colleagues will settle on some 'standards'. Also, don't be afraid to change your standards over time. –  Tony R Feb 16 '11 at 16:49
1  
+1 for "making it clear to the next person." And remember, that "next person" may well be yourself in 6 months or a year. If you ever have to re-learn a piece of code you wrote a while back, it's time to put a big ol' explanatory comment in front of it. Good naming/coding conventions + block comments explaining what the next section does is a powerful way of talking to the future. –  Peter Rowell Feb 16 '11 at 17:01
    
+1 back at you for "If you ever have to re-learn a piece of code you wrote a while back, it's time to put a big ol' explanatory comment in front of it." Definitely did that to myself a number of times! –  Tony R Feb 16 '11 at 19:26

First, considering your point (2). Documenting and writing well-organized code is a good thing regardless of whether you'll distribute it or not, isn't it? In both cases code will be written once, and then read hundreds of times—so the ability to quickly understand its structure and purpose is very important anyway.

In short, my opinion is that you better stick to writing concise self-documenting code even if you are just a hacking scientist. Though this means you may need a bit more of general programming knowledge. (On the other hand, such knowledge may be very useful even if you're not a coder.)

So, my suggestion is not a ‘simple reference’ and may be a bit overhead for your needs.

It is Steve McConnell's Code Complete book, which, I think, is quite an extensive resource on different programming conventions and coding practices, such as: variable naming, organizing code into routines and/or classes, refactoring and tuning, code documentation & commenting, general program design, etc. And it isn't about any particular programming language. (Here's table of contents; unfortunately, links there lead not to contents but to additional resources.)

Sorry if my answer will appear as not quite relevant.

share|improve this answer

I would recommend getting a mentor on your team.

If you are scientists, perhaps you are affiliated with an educational institution which also educates programmers or has contact with one that does?

That will most likely be the easiest - getting one of these programmers on your team to teach the things you need in an efficient way.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.