Jump to content
  • Advertisement
Sign in to follow this  
Angelic Ice

Unity Naming conventions, software documentation and version control

This topic is 907 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

Hey gamedev.net-community!

 

Lately I am cleaning up some C++-code (using Visual Studio 2015) and realised that I could improve a lot of things in terms of clarity, archiving/backupping and general software documentation.

 

I would like to give you a short overview of my questions:

 

1) What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style?

 

When I worked with Java, there were quite a lot of tips on how to use the Javadoc (Eclipse) and what common naming convections exist.

For C++, I realised there are quite a lot of different opinions (while Java has a major movement - for example camel case - if my observation is correctly).

What naming convention would you recommend? Should I follow the Google: https://google.github.io/styleguide/cppguide.html?

 

Some say that not everything within this style guide is really that great. Sergey Zubkov even goes so far and calls it a deal-breaker: https://www.linkedin.com/pulse/20140503193653-3046051-why-google-style-guide-for-c-is-a-deal-breaker

 

2) How to keep proper backups? Should I manually save them on my Computer (in ZIPs, ..)?

 

Backups are really important of course, I learned that the hard way. However even doing it manually costs time and leaves room for missing in between versions. The reliability of doing it by hand is simply quite low, at least when I perform these tasks.

What kind of software could help me out? Is a service like GitHub appropiated for a one programmer project?

 

3) How to provide a documentation for my software?

 

There are many different options that I found, but what would you recommend? Is there an industry standard?

 

 

 

I am well are that some of these questions are depending on personal taste, therefore I am looking for well proven solutions which may be industry standards.

 

In the end, thanks a lot for taking your time to read through this!

Share this post


Link to post
Share on other sites
Advertisement

What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style?

Yes, it's all opinion based.  Follow the one(s) you are comfortable with.  There is no industry style.  It might be informative to look at the naming conventions used in the standard library (defined through an ISO standards document) or through your favourite or most commonly-used toolkit.
 

How to keep proper backups?

Github, or even just a local git repo, or both, is perfect for single-developer projects.

Share this post


Link to post
Share on other sites

1) What naming conventions to follow?

Systems Hungarian. Or something else.

Is this all opinion based?

According to numbers I just made up, all humans share the same opinion: Systems Hungarian is the way to go.

Is there a/an common/industry standard style?

Some let you use your own style, some have their own style to which you must conform. No 2 companies use the same exact style.

2) How to keep proper backups?

Github, or even just a local git repo, or both, is perfect for single-developer projects.


3) How to provide a documentation for my software?

Doxygen.



L. Spiro

Share this post


Link to post
Share on other sites

1) What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style

 

Yeah it's mostly opinion-based because neither C nor C++ recommends one, so people usually import the naming convension of whatever language they used before. If you learned from Java you are probably going to import it's naming convention (Yuck! I hate lowerCamelCase! tongue.png) as did a lot of C++ library writers because Java was the hot new thing from the mid 90s to the mid 2000s. (Qt and Ogre3D are examples of C++ libraries that imported Java style.)

 

Personally, it was VB6, COM and MFC that were the hot new thing when I started programming, and I mostly skipped Java, jumping straight to C#, so my style is very Microsoft-influenced.

 

The Linux/GNU guys will probably use all_in_lower_case because that's how the standards look over there.

 

Really, style issues like naming are more like a programmer's signature so use whatever you want in your own projects. (Obviously, use your organization's standards at work.) As long as whatever style you're using is readable and understandable, and you stay consistent, your coding style is fine. smile.png

 

 

EDIT: I forgot to mention that the big names of the C++ community came up with a guide in late 2015 that recommends a style, but that's the "Stroustroup" style, which is a style that pretty much nobody uses, so I wouldn't recommend that one as the definite style for C++. (The rest of the guide is pretty good though.)

 

 

 

 


3) How to provide a documentation for my software?

 

In most of the case, it's Doxygen, although if you ever do .NET, SandCastle (or whatever the new one is called) is a bit better because it will generate docs that looks consistent with the one on MSDN.

Edited by Bearhugger

Share this post


Link to post
Share on other sites


1) What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style?

I would say it depends on what you're doing.
For example, if you're making an improved alternative to some standard C or C++ API, I would probably give the public API the same feel. I can't find the ISO C++ style guide, so here's boost's: http://www.boost.org/development/requirements.html#Design_and_Programming
If you're working specifically on a single OS, I would probably stick to that OS's API style. For example, Windows uses Systems Hungarian notation, while POSIX is more like the ANSI C standard or the C++ standard above.
In game development, Systems Hungarian and Camel Case seem to be the norm (I'm honestly not sure which I've seen more of, they're very similar when you're actually using APIs).

But it really is all opinion based. Some people find ISO C++ easier to read than Camel Case. Some people find the semantic information included in names with Systems Hungarian notation to be a waste of time, while others find it provides clarity in code. A lot of middleware will use one convention for its public API, but appear to have essentially no convention internally.


2) How to keep proper backups? Should I manually save them on my Computer (in ZIPs, ..)?

If you're using a versioning system (as is likely the case if you're hosting your project on Github), you don't need to worry about backups - the versioning system provides them for you.
If not, you could add it as a custom build step in your IDE.


3) How to provide a documentation for my software?

Like apparently everyone else here, I use doxygen. You just add a specially-formatted comment for everything that needs documentation and the tool generates documentation to share for you.
There have been a couple of times where I wished it were slightly different, but never enough to actually roll my own. And that's saying something, sometimes I reinvent the wheel just for fun.

Share this post


Link to post
Share on other sites

It might be informative to look at the naming conventions used in the standard library (defined through an ISO standards document)

 

This. A thousand times this.

 

Why is it that so many C++ programmers choose a Java style and (often) also throw out any and all uses of the standard library... 

Share this post


Link to post
Share on other sites


1) What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style?

 

Its entirely opinion based.  The only consesus is that when you pick one you should make sure you stick to it and use it consistently.
Remember though that ever company uses a slightly different convention so if you start a new job be prepared to use their standard at work even if it goes against everything you do at home.

 


2) How to keep proper backups? Should I manually save them on my Computer (in ZIPs, ..)?

 

I use a combination of Git for version control and Dropbox for backups.

 


3) How to provide a documentation for my software?

 

I don't really do this.  A few companies I've worked at have had big announcements that they are going to start using Dropbox and it lasts for a month or two and then slowly stops being used and it ends up with documentation that is out of date and doesn't actually reflect what the code is doing anymore :(

Share this post


Link to post
Share on other sites

What naming conventions to follow? Is this all opinion based? Is there a/an common/industry standard style?

Yes, it's all opinion based.  Follow the one(s) you are comfortable with.  There is no industry style.  It might be informative to look at the naming conventions used in the standard library (defined through an ISO standards document) or through your favourite or most commonly-used toolkit.

While it's true that it's opinion based, some convention have been put more thought than others, and it's important to understand the rationale.

For example for class member variables, the most popular are mMyVariable or m_myVariable.
I prefer 'm_myVariable' because of autocomplete. Once you've typed 'm_'; 90% of the suggestions from autocomplete will be the member variables. Whereas if you just type 'm', the suggestions are crowded by a lot of irrelevant variables and functions, mostly from the global namespace.
However my colleague prefers mMyVar because m_myVar strains his carpel tunnel syndromme (the need to hold shift to type the underscore). So we sticked to mMyVar because his health is more important.
Another option is to always use this->myVar which makes perfect clear it's a member variable and works with autocomplete too. But is more noisy and harder to make everyone follow it. Edited by Matias Goldberg

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!