AusGamers Forums
Show: per page
1
Coding style / comments
plok
Brisbane, Queensland
511 posts
I think there's a few coders in the QGL crew... what are the opinions regarding a company coding style? It's recently come up and there's a couple of team members who are pushing for formalising (enforcing) a coding style (that we would need to write). I'm mostly against it, preferring code reviews and relying on the assumption that we're all vaguely competent... anyway, any opinions out there?
06:47pm 24/12/12 Permalink
system
Internet
--
06:47pm 24/12/12 Permalink
Spook
Brisbane, Queensland
34819 posts
lolz, ive just signed up for a code review team at work, to review the style of coding and make sure everyone follows teh same style.

tbh, we use templates wherever possible and in my experience people follow the style of the templates

id certainly never knock back code that works just because someone brackets on the wrong line, but i guess thats teh future!
07:00pm 24/12/12 Permalink
mooby
Brisbane, Queensland
6231 posts
few naming conventions, code reviews and adhear to patterns is what you need.
07:04pm 24/12/12 Permalink
mooby
Brisbane, Queensland
6232 posts
imo, you should more concerned about principals than style
07:06pm 24/12/12 Permalink
Raven
Melbourne, Victoria
7569 posts
Yup. 'Style' should be mostly enforced by the developer, not by application. However that said, feel free to use formatters. But don't, for gods sake, enforce it using something like a SVN hook.

Don't worry about whiny developers who b**** about tabs versus spaces, curce on newlines vs same line, spaces near brackets etc. They'll adapt.

You're better off putting the time you spend bickering about coding style in to how you test your code.
07:11pm 24/12/12 Permalink
Whoop
Brisbane, Queensland
21056 posts
If every code looked the same
We'd get tired of debugging each others'
07:23pm 24/12/12 Permalink
TicMan
Melbourne, Victoria
8377 posts
#1 rule should be that it's readable and DOESN'T require comments IMO.
08:15pm 24/12/12 Permalink
Spook
Brisbane, Queensland
34820 posts
been out of the loop for a bit ticcles? code always needs commments.

too busy bigwiggin these days?

edit: either that or you dont do much support work.
08:17pm 24/12/12 Permalink
plok
Brisbane, Queensland
512 posts
I'm actually with Tic on this. "Comments are lies waiting to happen" is something I find myself agreeing with more and more. With the added caveat of "and in the meantime they are ugly and in the way". Classes where every member has a getter and a setter, with a comment in all three places are getting to me. In 99% of cases, if your code needs a comment to be understood then I think there's a problem with the code. Same applies for style. The argument that it's better to at least be consistent is worth the price doesn't ring true for me. If there's a bug in an area of code and it really needs to be understood, then I've never found that the style makes any difference. It only helps to understand relatively straight-forward code that adheres to a style... ASSUMING the style isn't telling more lies.
08:43pm 24/12/12 Permalink
koopz
Brisbane, Queensland
9811 posts
tbh, we use templates wherever possible and in my experience people follow the style of the templates


id certainly never knock back code that works just because someone brackets on the wrong line, but i guess thats teh future!



god I hate your internet avatar... so much


08:46pm 24/12/12 Permalink
JakeG
Thailand
1147 posts
What's it like employment wise for programmers in Oz? Someone said to me he gets his coding done in India for 5 bucks an hour or something. I'm interested because I'm learning and wondering what it would take to start getting good money.
08:47pm 24/12/12 Permalink
Raven
Melbourne, Victoria
7570 posts
#1 rule should be that it's readable and DOESN'T require comments IMO.

I absolutely agree - this is something I try to beat in to my juniors early - that code should be self-documenting.

What's it like employment wise for programmers in Oz? Someone said to me he gets his coding done in India for 5 bucks an hour or something. I'm interested because I'm learning and wondering what it would take to start getting good money.

Few months ago I had 7 recruiters call me in 10 days.
08:48pm 24/12/12 Permalink
Spook
Brisbane, Queensland
34824 posts
its like you guys dont actually code anymore. no one writes code that doesnt need documentation, you are kidding yourself if you believe otherwise.
09:59pm 24/12/12 Permalink
fpot
Gold Coast, Queensland
21990 posts
Don't comments help people who don't understand code know what's going on? Or is there pretty much no need for that?
10:05pm 24/12/12 Permalink
Dazhel
Gold Coast, Queensland
5528 posts
^ The people who don't understand code should probably not be poking around in the code anyway.

re: OP's question of coding style - most languages have some form of coding guide nowadays anyway.
I'd probably say informally adopt the language guidelines, respect the style of code that's already been written (i.e. no mass reformatting exercises, they can introduce bugs), and prefer some common sense instead of a formal document.

if you're going to have a written standard though, make sure it includes reference to bamboo shoots up the fingernails for anybody who uses hungarian notation.
10:34pm 24/12/12 Permalink
Calsy
60 posts
Of course you want to implement a coding style when you have multiple people of varying skill working on a project . To simply assume that someone is capable of doing the job and that they should 'be ok' is pretty f***** lazy and poor management if you're a person in said position.

Projects can last for several years with many iterations with many people involved. People come and go all the time and you want to limit the time it takes for a new person or even someone crossing over to say maybe a different module to get up to speed.

Time is your greatest enemy in most projects, so anything that can decrease the effort required for a person to get there head around the code is a bonus. That's where a uniform coding style pays off big time, rather than a mish mash of s*** glued together.

Documenting you're code is critical also, again its lazy not to do so. I'm not saying document every line of code be smart give some explanation on this block of code say performing a certain action in a loop or something what are you achieving here. Big name variables aren't the answer. Do your comments after finished coding, no long winded speeches a couple of one liners here and there. Its called being a good developer.

So called 'pros' who say they been doing this s*** for however many years tend to get lazier as they get old and they cut corners. It's just the way it goes.
11:51pm 24/12/12 Permalink
Calsy
61 posts
Its what separates the hacks from the pros, being able to code to a formal standard.

It also says something about the person, whether they take pride in their work and take a holistic view of the project, looking to improve process and standards within the team OR do as little as possible to get the job done and only worry about the code they are writing and when they leave well f*** it not my problem.

Yes the later sounds appealing, most people do it, but doesn't make it the best way.
12:22am 25/12/12 Permalink
Dazhel
Gold Coast, Queensland
5529 posts
lol soap box time
12:24am 25/12/12 Permalink
Whoop
Brisbane, Queensland
21061 posts
I mix ' with " and if I'm feeling really naughty, don't bother putting things in ( ) when I don't have to. Also all my variable names are swear words.
12:48am 25/12/12 Permalink
Hogfather
Cairns, Queensland
13280 posts
We have a coding style at my office. My style.

I'm paying the wages so I get to say how the code is written (and I'll be the one maintaining it in 7 year's time, so it should at least be recognisable...)
01:05am 25/12/12 Permalink
stinky
USA
3750 posts
its like you guys dont actually code anymore. no one writes code that doesnt need documentation, you are kidding yourself if you believe otherwise.


except for perl AMIRITE!?! mostly because even with comments out the wazoo perl can never be read once written. :)

Also ... I find just as important as code style documentation style ( and formats ) ! I used to be all about the wiki everything mans ... but now I'm starting to like markdown stored in the versioning system along with the code.

* fully readable ( and understandable ) in plain text ( and editable in anything from notepad to an IDE ).

* versioned, forkable, etc

* can be displayed ( and edited ) as a wiki - https://github.com/github/gollum

* can be compiled into online documentation ( bonus points for doing it with CI )
02:08am 25/12/12 Permalink
Nerf Lord
Brisbane, Queensland
7073 posts
An extremely useful example of a common coding style which I picked up from somebody who I used to work with (who is somebody on here, but I don't know who, hopefully somebody I've never argued with :P) was to put all class scope variables at the top of the class, above the constructor. It makes it very clear what the class has to work with, and I can't even read code without that any more.

I don't know about larger coding styles, but I do find commenting a bit of a double edged sword sometimes, when many times the code can be made more readable than the comments and will always stay up to date. Sometimes tricky things just really need to be documented though, even if I made it within a few months I will very likely have forgotten the exact mechanics of how and why. This is how I code now, all other styles and more-or-less-levels of commenting are wrong. ;) Though come to think of it, I only just realised that NullLink should call Put...
07:19am 25/12/12 Permalink
mooby
Brisbane, Queensland
6233 posts
Don't comments help people who don't understand code know what's going on?

Comments help with intellisense. More important are tests. They prove what the code is doing. When you refactor, you still have that confidence you havent broken the intent.
07:59am 25/12/12 Permalink
redhat
Sydney, New South Wales
863 posts
Comment your code.

Only exception is a language where there's only one way to do something so it should be self explanatory.
12:07pm 25/12/12 Permalink
Raven
Melbourne, Victoria
7572 posts
Comments should explain why, not how. Therefore for most purposes, comments are not necessary and the code itself should be self-explanatory.
12:29pm 25/12/12 Permalink
euphoria
Gold Coast, Queensland
2069 posts
This is for C#: StyleCop You can customise it to your team's preferences, but it's a great starting point. First thing we do in code reviews: Run Code Analysis (FxCop is the free version) and then run StyleCop. If warnings from those pop up, the review stops and the dev has to sort that crap out first.
12:41pm 25/12/12 Permalink
parabol
Brisbane, Queensland
7396 posts
#1 rule should be that it's readable and DOESN'T require comments IMO.

Sure, maybe if you are:

1. working on a small project, AND/OR
2. using an OO language with easy-to-read class names / camelCaseVariables, AND/OR
3. using pre-existing, mature libraries without adding much functionality of your own.

In these situations the relationships between objects and functions/methods are inherently high-level, clean and straightforward due to the underlying language and your use of variables/libraries.

Now move onto something even slightly low level or creative (e.g. developing firmware or device drivers that talk with real hardware) and your comment-free advice breaks down immediately, as you generally don't have those crutches to hold you up.

Some of the worst code that I have ever seen has been from people who have gotten into embedded systems design and decided that their code was too obvious to understand to bother commenting. It was great for them, as it provided job security since no-one else could easily pick up the code-base.
01:29pm 25/12/12 Permalink
simul
Brisbane, Queensland
1455 posts
Comment when its useful, don't when its not:
- Anything that isn't the obvious way of doing something (Doing X because of Y)
- Coding around particular issues (dealloc'ing this to stop an overflow error in the PDF rendering)
- Things that aren't enum'd properly (1 means this)
- Anything that is API-like - library endpoints (function load(x))
- Things that are more parseable - parsing/scraping sensor/web/other data
- Its good to comment the pattern being used if its not following convention (ala static __instance)

All that being said, theres nothing worse than walking into code and every second line is commented, and the comments merely say what the code is saying anyway. Comment meaning with the assumption that the reader is an expert in the language - thats the litmus test in my mind. Of course it depends on how many people in the team, but to be honest if your team is that large that you are requiring documentation to communicate then something is wrong.

The hope would be if your doing OO, then your classes are abstracted/named to the point where they make sense (that means good composition, not insane inheritance) - and the reader can drill down when they want more information.

For comment styling, at least stick to a documentable format (for me usually doxygen) - and do it consistently (we use a series of specific keywords plugged into doxygen for documentation generation). Or if you the IDE/language has a preferred way of commenting #pragma mark.
04:15pm 25/12/12 Permalink
system
Internet
--
04:15pm 25/12/12 Permalink
AusGamers Forums
Show: per page
1
This thread is archived and cannot be replied to.
 

Advertise with Us | Download Media Kit | Privacy Policy | Contact Us
© Copyright 2001-2014 AusGamers™ Pty Ltd. ACN 093 772 242.
A Mammoth Media web development / Australian VPS Hosting by Mammoth Networks