Good coding conventions - Discussion

[Josh]

OK, a little background on the reason behind this post.

I have recently started teaching myself Java in an effort to start dabbling in Android development. I am using the Eclipse IDE in combination with the Sam's Teach Yourself Java in 21 days - Covering Java 7 and Android book.

As a course of habit, I find myself skimming each chapter so that I can see what things I might possibly miss by assuming I knew all of the material (yes, even variable types. I actually learned something reading through the types). This is where the discussion I want to have arises from.

When coding, I know common coding conventions such as coding indentation for readability, CONST/Finals being written in ALL CAPS in order to identify them as such. I was wondering, what other practices do each of you follow as you code and which are considered industry best practice?

[Renegade]

Ah... I see someone is looking to start a war!

Pascal for this, camel for that, CAPS for another, and _these get underscores, while strThose get a pretty prefix, and so do btnThese.

Object.toString() or Object.ToString() or Object.tostring()?

I stick mostly to C#, Java, C and VB naming conventions. I like a bit of this and a bit of that. e.g. I like private field names with an _underscore and camel case:

_somePrivateFieldName

I'm not fond of:

m_something

I like public properties in Pascal case:

SomePublicPropertyName

I also like method names in Pascal case.

I like controls in Hungarian:

btnGoButton
pbxBigPictureBox
wbrMainWebBrowser
lblInputLabel
txtTextbox
etc.

While this is short:

if (condition)
  DoSomething();

I prefer:

if (condition
{
  DoSomething();
}

It's just easier to see/read when skimming. I'm not usually very fond of:

condition ? DoSomething() : DoNothing();

It has its uses, but often it's harder to read. Sometimes it is easier... depends... No right answers as far as I can see. Verbose and terse both serve a purpose.

I think following conventions is more important when you work in larger teams, and especially when other people, that you will never meet, end up using/modifying your code.

I do like lots of comments though.

Reading on variable types really is essential for a language though. Some languages do things that you would NEVER expect with some types, and as you're reading through, you end up going, "Ah... now I see what that didn't work..." They usually all make sense in their own contexts. Just different flavours. e.g. If you allocate memory for an integer but don't assign a value, what is the value? zero? null? Both are valid assumptions. Same for a string. Is it null or empty?

[Ath]

+1 on all Renegade said

@Josh, when working with Eclipse, I always use the default format layout (Ctrl-Shift-F), as it's a Java-layout standard on it's own, only I've made line and comment widths a bit wider then the default 80 characters, 160 is usually most optimal.
Aligning variable declarations does make source more readable, so that's an option I tend to enable for projects with larger sources as well.

[wraith808]

another +1 on what renegade said.  But in the end, I think it's a matter of audience and consistency when dealing with any project rather than slavish attention to anyone else's rules.

Other than I hate the rule we have at work with no underscores!  so private variables are thisIsAProperty and public ones are ThisIsAProperty.  I know they did it because we should be using autoimplemented properties now... but in some cases you can't and that rule sucks!

[TaoPhoenix]

Ah... I see someone is looking to start a war!

Pascal for this, camel for that, CAPS for another, and _these get underscores, while strThose get a pretty prefix, and so do btnThese.
...
I stick mostly to C#, Java, C and VB naming conventions. I like a bit of this and a bit of that. e.g. I like private field names with an _underscore and camel case:
_somePrivateFieldName
I'm not fond of:
m_something

Heh I'm no coder, so allow me to be a pest as a Humanities type intruding where I don't belong!  

I like CamelCaps aesthetically. I hate Under_scores. : )

[40hz]

I'm not much of a coder. But I do work a lot with administrative scripting as part of my job.

My only suggestion is that whatever coding conventions you adopt, you use them consistently.

I often transfer scripts to people. And I sometimes inherit scripts written by others. And within the community of sysadmins I work with, the key factor for what constitutes "good" or "best" coding practice is consistency. As long as your coding conventions are applied logically and consistently, they can be understood and modified - or fixed - if in error.

That also makes them easy to change if you learn (or discover) a better (for you) way to do something. In my case, I currently dislike underscores - and very much like CamelCaps - although there was a time when I preferred the exact opposite. (Aging eyesight has a lot to do with it.)

I also agree with Renegade about comments. Good comments make the difference between partial and complete insanity when you revisit something you previously wrote, or when you have somebody else's zen-telegram dropped on your desk for a fix, mod, or rewrite.

Ditto with Renegade's general preference for not getting "fancy" with what you can get away with when it comes to formatting or putting multiple statements on one line. I was taught: When in doubt - spell it out. And over time I also learned that it's usually better to "spell it out" even when you aren't. Because your "style" will change as you learn more and gain experience. And there's nothing worse or more embarrassing than confronting a piece of code you wrote a few years previously and no longer knowing exactly how it works. Most times I've had it happen to me was when I picked up a "little trick" someplace, or decided to get cute just to show off how savvy I was about what I was doing. I've since learned better and have become a much happier sysadmin because of it.

That's about all I can suggest. I'll leave the rest of the discussion to the real pros we've got here.

Good luck and happy coding!

[TaoPhoenix]

I'm not much of a coder. But I do work a lot with administrative scripting as part of my job.
In my case, I currently dislike underscores - and very much like CamelCaps - although there was a time when I preferred the exact opposite. (Aging eyesight has a lot to do with it.)

My eyes have sorta held steady for 20 years, I just somehow conceptually hate underscores. When pushed, I'l use dashes. When did the battle over Dashes vs Underscores happen? Does someone have a nice meaty 3000 word blog to link to?

[mouser]

40hz said the most important thing, imho, and where i often fail, to my deteriment:

My only suggestion is that whatever coding conventions you adopt, you use them consistently.

Particularly when it comes to variable and function naming -- pick a convention and stick with it.

I suppose when it comes to style choices, my view is to always aim for clarity and avoid cleverness.

Cleverness always ends up meaning "hard to maintain" in the long run.

Most things are clearer in 3 lines of code than crammed into 1 line.  Choose the 3 line way.

In a similar vein, don't be afraid of nice long variable names and function names.. I personally have no problem with names made up of whole long phrases.

And my #1 suggestion to new coders:  Look for places where you repeat yourself.. When you find such an occurrence, that's your signal that you need to restructure your code and use a function or object.  Avoid repetition of code and you are half way there.

If you want to try to meditate on good coding -- from my stand point it all boils down to writing code so that it's easy to MAINTAIN (modify, extend, etc.).  You should always be organizing code so that it would be easy to change how something works.  The more likely you are going to actually need to change something, the more you need to modularize your code around that component to make it easier to replace that piece of code.

[Stoic Joker]

My coding style is an ecclectic mixture of thing I picked up along the way. This is a side effect of being self taught, as thre was no one to force me to do things their "correct" way. However one thing that has proven handy is that in addition to commenting I always put a header comment above each function stating (in short) what it is/does.

This header is outlined with some manner of (basically lamed assed) ASCII "art" so for example:

Code: (c)

  //===========================================================
//--0000---------+++--> This Rewards Good Input With a Cookies:
BOOL isInputGood(int iPut) { //--0000----------------+++-->
    if(iPut) GiveCookie = TRUE;
   else GiveCookie = FALSE;

This allows me to do 2 things:

• Quickly skim through collapsed code looking at the right edge of the editor for the function I'm trying to find later.
• Know instantly at a glance how old the code/function as I periodically change the style of the header outline.

[Renegade]

My coding style is an ecclectic mixture of thing I picked up along the way. This is a side effect of being self taught, as thre was no one to force me to do things their "correct" way. However one thing that has proven handy is that in addition to commenting I always put a header comment above each function stating (in short) what it is/does.

In Visual Studio with C# you can add comment documentation above a method very easily by using 3 slashes:

///

In the past I've kind of ignored doing that, but I've learned that it is a very, very nice little feature, and that it's best to take advantage of it whenever possible.

Here's a simple example:

Code: (csharp)

        /// <summary>
        /// A simple constructor override to let you set the HTML of the browser and create an arbitrary number of buttons.
        /// </summary>
        /// <param name="html">The HTML for the browser.</param>
        /// <param name="buttonTexts">The text for each button. The form returns the text value for the clicked button when it closes.</param>
        public HelpWindow(string html, string[] buttonTexts)

You get the summary and a field for each parameter all for free when you type ///. Very simple, fast and elegant.

[TaoPhoenix]

Other than I hate the rule we have at work with no underscores!  so private variables are thisIsAProperty and public ones are ThisIsAProperty.  I know they did it because we should be using autoimplemented properties now... but in some cases you can't and that rule sucks!

I sorta get the use of dividers, but what am I missing about Underscores vs Dashes? I somehow mind dashes less, and I have no idea why.

Edit: Oops, per Mouser, I repeated myself. I'll go slink into a corner now. : (

[Renegade]

I sorta get the use of dividers, but what am I missing about Underscores vs Dashes? I somehow mind dashes less, and I have no idea why.

What language are you using? Dashes aren't legal in a lot of languages (I can't think of one where they are legal) because that creates ambiguity, e.g.:

Code: (csharp)

int something = an-integer - another-integer;

Compared with:

Code: (csharp)

int something = an_integer - another_integer;

[Stoic Joker]

In Visual Studio with C# you can add comment documentation above a method very easily by using 3 slashes:

///

That depends on which version of VS you're using. For some reason three slashes will break your code in VS2005 (yes I still use it frequently). But I (am nutz and still) primarily work in pure Win32 API C++

[Renegade]

In Visual Studio with C# you can add comment documentation above a method very easily by using 3 slashes:

///

That depends on which version of VS you're using. For some reason three slashes will break your code in VS2005 (yes I still use it frequently). But I (am nutz and still) primarily work in pure Win32 API C++

I haven't used 2005 in a long time. I'm using 2010 now, with no plans to migrate to 2012 at the moment.

But I didn't know that it broke in 2005. Might have been a reason that I didn't use them way back then.

[TaoPhoenix]

What language are you using? Dashes aren't legal in a lot of languages (I can't think of one where they are legal) because that creates ambiguity, e.g.:

Code: (csharp)

int something = an-integer - another-integer;

Compared with:

Code: (csharp)

int something = an_integer - another_integer;

(Ghetto) None, becuz I' no programmer bro. I just be a dumb humanities birdie. (/Ghetto)

So my only use case is naming files when I don't feel like seeing a lot of %20's in my file names on remote sites. I use spaces the rest of the time in Windows. So I never ever had a use case for Under_Scores, and now that I'm cranky and senile at an early age they annoy me. : )

[Renegade]

(Ghetto) None, becuz I' no programmer bro. I just be a dumb humanities birdie. (/Ghetto)

So my only use case is naming files when I don't feel like seeing a lot of %20's in my file names on remote sites. I use spaces the rest of the time in Windows. So I never ever had a use case for Under_Scores, and now that I'm cranky and senile at an early age they annoy me. : )

Ah. Got it. I was thinking way back to when spacing was significant and a single space could break things. Under those conditions, it would be possible to have dashes in variable names with the further condition that operators like minus were padded on the left & right with a space. Couldn't think of a language that did it, but I could imagine it being possible.

[TaoPhoenix]

Ah. Got it. I was thinking way back to when spacing was significant and a single space could break things.

And so was I, and for that dashes worked for me because you don't do math on file names. So somewhere underscores made me grumpy.

[wraith808]

In Visual Studio with C# you can add comment documentation above a method very easily by using 3 slashes:

///

That depends on which version of VS you're using. For some reason three slashes will break your code in VS2005 (yes I still use it frequently). But I (am nutz and still) primarily work in pure Win32 API C++

Maybe it's the Win32 API C++?  Because the /// convention works for me in VS2005, and I've been using them religiously.  I didn't pay attention to the C++ code- it's mostly get in and get out without making a mess.

[Stoic Joker]

In Visual Studio with C# you can add comment documentation above a method very easily by using 3 slashes:

///

That depends on which version of VS you're using. For some reason three slashes will break your code in VS2005 (yes I still use it frequently). But I (am nutz and still) primarily work in pure Win32 API C++

Maybe it's the Win32 API C++?  Because the /// convention works for me in VS2005, and I've been using them religiously.  I didn't pay attention to the C++ code- it's mostly get in and get out without making a mess.

Now that is a good possibility, as I almost never use C#. I had one C# project that I was doing for the office but it hit the wall early last spring due to "Scope Conflicts" (e.g. Nobody could/would nail down exactly WTF'ing thing was supposed to do).

[TaoPhoenix]

I had one ... project that I was doing for the office but it hit the wall early last spring due to "Scope Conflicts" (e.g. Nobody could/would nail down exactly WTF'ing thing was supposed to do).

Eew Scope clashes. I just ran into that today with my commission. : (

[Renegade]

I've had people define scope as "good". I mean that quite literally. Huh? Yep. Not a joke.

[TaoPhoenix]

I've had people define scope as "good". I mean that quite literally. Huh? Yep. Not a joke.

Good scope is good! What's the problem? Who are you to argue with Good Scope? 

[40hz]

When pushed, I'l use dashes. When did the battle over Dashes vs Underscores happen? Does someone have a nice meaty 3000 word blog to link to?

I was always under the impression that back when coding was mostly done on a slightly fuzzy green screen in all upper case that most programmers felt that:

    THIS_IS_SOMETHING

was more obvious and easier to read than:

    THIS-IS-SOMETHING

At least I remember being told to use underscores rather than hyphens when I was doing things in BSD "because_that_was_the_way_it's_done."

There was also something about the hyphen being an official part of ASCII - whereas the underscore was not. But I forget why some people felt that was significant. Probably had something to do with the underscore being considered more a 'dealer's choice' sort of thing, whereas the hyphen was already spoken for.

Then I got into networking and you soon learned that some implementations of DNS and NETBIOS (and possibly early versions of AD?) had huge problems with names containing underscores. So much so that it often resulted in a broken network when they encountered them. So the word then became never to use underscores (with Microsoft) until Redmond finally got that fixed quite a bit later. However, some network devices still have problems with underscores to this day - so for network applications and environments, underscores are best avoided. But I don't think any of that was ever much of an issue with general programming unless one or the other character was illegal or reserved by the specific language.

FWIW - in most network situations I avoid using both those characters.

[Jibz]

Don't know if that had anything to do with it, but AFAIR hyphens were not (originally) allowed in filenames on CDs (ISO_9660^w from 1988).

[Stoic Joker]

FWIW - in most network situations I avoid using both those characters.

+1