Writing Respectable Code

[dejai]

I would like to get your input in writing respectable code for any given project. Firstly I believe that style and readability are critical in writing good code, I have my own style guide that is very similar to that of Google's. Secondly if you are using code more than twice and by writing the entire function out you save more lines then do it. If not it's probably not needed. We can't always write test functions but if we need to write rock solid code we have to, humans will screw something up tests reduce that risk. Don't over engineer the problem. A pong game can fit in a single file if not 2, no more should be needed. Refactor if the code gets ugly. Over commenting is a problem, never comment on the language always on what you are trying to do, some leeway if it's a giant hack (but then it shouldn't be in the code!). Please feel free to criticize and add.

[davidthefat]

LOL Im probably the messiest code... I just code away then make comments later(Thats IF I comment, only IF)... that leads to many problems along the way... especially when working with classes Well it works I guess...

[andrew]

In addition to what you already have, this also has good advice.
This one is even better.

[Pennywise]

This can be quite useful
http://lazyfoo.net/articles/article02/index.php

[K-Bal]

I would not write a Pong in 2 files. I make classes for the game objects and every class gets two files and if one thinks that is overkill for a Pong, one probably has not much experience in software design The key is that I can expand this program. If the simple Pong does not suit my needs anymore, I can add PowerUps or make it 3d without changing my logical structure and hacking things in.

That is the reason why beginners should make a Pong and not an MMO: to learn software design. You have to learn these things in order to apply them somewhere.

[zeid]

If you re-look over your code enough and program alot, many of the conventions for writting good code come naturally. Reworking code you delete the redundant comments and remember not to write them as much in the future, 10 logic errors later and you start indenting properly, there are reasons for all of these conventions and they aren't just there to help the people looking back on the code. Most people seem to get sloppy when they aren't exactly sure what they are wanting to create, how to structure things or of the logic behind what they are doing.

The key is that I can expand this program. If the simple Pong does not suit my needs anymore, I can add PowerUps or make it 3d without changing my logical structure and hacking things in.

Extendible and modular design is the big thing nowadays with OO. I think its great creating something so concise and structured and yet very powerful.

Keeping code well maintained and ordered is time consuming though, so sometimes you just have to be a little sloppy to get that assignment it. Use a few hacks to get the result you need. Of course you should always try and avoid these things, but we don't live in a perfect world.

[hurstshifter]

I would not write a Pong in 2 files. I make classes for the game objects and every class gets two files and if one thinks that is overkill for a Pong, one probably has not much experience in software design The key is that I can expand this program. If the simple Pong does not suit my needs anymore, I can add PowerUps or make it 3d without changing my logical structure and hacking things in.

That is the reason why beginners should make a Pong and not an MMO: to learn software design. You have to learn these things in order to apply them somewhere.

+1

I seperate all of my objects into 2 files. And EVERY function gets a function description header similar to this...

Code: Select all

/*************************************************************************
*Function Name: int foo()
*             Inputs: None
*           Returns: int
*      Description: This function will attempt to pwn all you
*                         noobs.
**************************************************************************/

Even if it is simply an accessor function that returns a value. This practice was drilled into me by one of my college professors.

[Ciidian]

I am a firm believer in separating code into multiple files. It's much easier to maintain and debug instead of reading through code all bunched in one file. I think my first Pong game had 7 files for it: Ball.h, Ball.cpp, Paddle.h, Paddle.cpp, Draw.h, Draw.cpp, and main.cpp.

I was always taught from the beginning to keep classes separated in their own files, and have never seen the advantage of throwing them all into one file.

[Falco Girgis]

I feel like this isn't enough to write "respectable code." These are simple conventions. Following these offer no guarantees that your program isn't written like shit.

What about OO paradigms? What about proper data abstraction? What about OO design overkill? These are the things that separate the newbie programmer from the experienced software engineer. Your code not only needs to be neat, but modular. Modularity is much more important in the long run than following a style guide or commenting properly.

[Spikey]

Most companies have a coding standard that you must follow. Being a good coder means being able to adapt to a changing environment. Modularity is important, because it means your planning ahead. Not sure exactly what respectable code would define as. I don't know... I guess that would be simple, yet elegant code that can still be read easily. This points back at coding standards. I have this page bookmarked, http://www.possibility.com/Cpp/CppCodingStandard.html

there's a coding standard by John Carmack from ID software, it's at least worth looking at.


Also there's a local game company here that had a contract with Disney and they blew it by one programmer adding a joke into the source code. something like a string outputting 'John is a fag' John happened to be the project manager, and it was true that John was a dick. But during presentation time to Disney, that message conveniently popped up. ya not good lol... Disrespectable code?

[Falco Girgis]

^ I don't really agree.

These are trivial things. Do you capitalize your class names? Are your object names lowercase? Are your method names lowercase?

Big deal. These don't really mean much. "Respectable Code" is more on the engineering level, of how your code is broken up, how it works, how it integrates with other code, and how users interact with your library/API/code.

Modularity and the integrity of your code on the engineering level is always going to be more important than you having cute little comments and following a company's (or person's) arbitrary coding standard to their liking.

[K-Bal]

Do you capitalize your class names? Are your object names lowercase? Are your method names lowercase?

My method names are uppercase

I sign what Falco said. These coding guidelines are not that much important as long as you keep them consistent in one project. I personally don't give a fuck about commenting. Only some real hacks are commented in my code, the rest should be understandable without comments. Some important things are modularity and a consistent and easy-to-use public API.

[dejai]

I agree with gyro, this isn't about syntax it's about semantics. The issue with software is there is no set model of how to approach any given problems. There are more efficient models however yet "the most efficient" is generally not the "optimal" solution from a programming standpoint as it would most certainly be written in assembly! I tend to think OO as intelligent agents that talk to each other to form a program. If you have a dumb agent, chances are it's not needed. (I would write pong in C :P classes are needed for something with more than one object ).

[zeid]

Modularity and the integrity of your code on the engineering level is always going to be more important

Yes, this is absolutely true.

These are trivial things.

To a degree they are, the reason you try and enforce good habits like camelCase and so on is to do with working with other people.

Some of these habits are useful for keeping things neat tidy and well laid out, they don't make you a better coder but make your code easier to read for you and others. Other ones of these practices only really help when you are working on a big project with alot of people. I have no doubt that writting redundant comments all through your classes, poorly named variables and class names, with no indenting is going to royally piss off those who have to interact with your code or change anything.

So yes there are more important things then coding conventions to worry about. But it is good to get into the habits earlier rather than later.