- Software Version Control Naming Conventions
- Software Naming Standard
- Naming Convention Rules
- Software Engineering Naming Conventions
This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names.
Word Choice
In computer programming, a naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types, functions, and other entities in source code and documentation.
✓ DO choose easily readable identifier names.
For example, a property named HorizontalAlignment is more English-readable than AlignmentHorizontal.
✓ DO favor readability over brevity.
The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis).
X DO NOT use underscores, hyphens, or any other nonalphanumeric characters.
X DO NOT use Hungarian notation.
X AVOID using identifiers that conflict with keywords of widely used programming languages.
According to Rule 4 of the Common Language Specification (CLS), all compliant languages must provide a mechanism that allows access to named items that use a keyword of that language as an identifier. C#, for example, uses the @ sign as an escape mechanism in this case. However, it is still a good idea to avoid common keywords because it is much more difficult to use a method with the escape sequence than one without it.
Using Abbreviations and Acronyms
X DO NOT use abbreviations or contractions as part of identifier names.
For example, use GetWindow rather than GetWin.
X DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.
Avoiding Language-Specific Names
✓ DO use semantically interesting names rather than language-specific keywords for type names.
For example, GetLength is a better name than GetInt.
✓ DO use a generic CLR type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type.
For example, a method converting to Int64 should be named ToInt64, not ToLong (because Int64 is a CLR name for the C#-specific alias long). The following table presents several base data types using the CLR type names (as well as the corresponding type names for C#, Visual Basic, and C++).
| C# | Visual Basic | C++ | CLR |
|---|---|---|---|
| sbyte | SByte | char | SByte |
| byte | Byte | unsigned char | Byte |
| short | Short | short | Int16 |
| ushort | UInt16 | unsigned short | UInt16 |
| int | Integer | int | Int32 |
| uint | UInt32 | unsigned int | UInt32 |
| long | Long | __int64 | Int64 |
| ulong | UInt64 | unsigned __int64 | UInt64 |
| float | Single | float | Single |
| double | Double | double | Double |
| bool | Boolean | bool | Boolean |
| char | Char | wchar_t | Char |
| string | String | String | String |
| object | Object | Object | Object |
✓ DO use a common name, such as value or item, rather than repeating the type name, in the rare cases when an identifier has no semantic meaning and the type of the parameter is not important.
Naming New Versions of Existing APIs
✓ DO use a name similar to the old API when creating new versions of an existing API.
This helps to highlight the relationship between the APIs.
✓ DO prefer adding a suffix rather than a prefix to indicate a new version of an existing API.
This will assist discovery when browsing documentation, or using IntelliSense. The old version of the API will be organized close to the new APIs, because most browsers and IntelliSense show identifiers in alphabetical order.
✓ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix.
✓ DO use a numeric suffix to indicate a new version of an existing API, particularly if the existing name of the API is the only name that makes sense (i.e., if it is an industry standard) and if adding any meaningful suffix (or changing the name) is not an appropriate option.
X DO NOT use the 'Ex' (or a similar) suffix for an identifier to distinguish it from an earlier version of the same API.
✓ DO use the '64' suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. You only need to take this approach when the existing 32-bit API exists; don’t do it for brand new APIs with only a 64-bit version.
Portions © 2005, 2009 Microsoft Corporation. All rights reserved.
Reprinted by permission of Pearson Education, Inc. from Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.
See also
Is there any guideline or standard best practice how to version a software you develop in your spare time for fun, but nevertheless will be used by some people? I think it's necessary to version such software so that you know about with version one is talking about (e.g. for bug fixing, support, and so on).
But where do I start the versioning? 0.0.0? or 0.0? And then how to I increment the numbers? major release.minor change? and shouldn't any commit to a version control system be another version? or is this only for versions which are used in a productive manner?
Lukeclosed as primarily opinion-based by bummi, animuson♦Aug 2 '13 at 15:43
Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.
locked by Flexo♦Mar 21 '17 at 21:32
This question exists because it has historical significance, but it is not considered a good, on-topic question for this site so please do not use it as evidence that you can ask similar questions here. This question and its answers are frozen and cannot be changed. See the help center for guidance on writing a good question.
Read more about locked posts here.
12 Answers
You should start with version 1, unless you know that the first version you 'release' is incomplete in some way.
As to how you increment the versions, that's up to you, but use the major, minor, build numbering as a guide.
It's not necessary to have every version you commit to source control as another version - you'll soon have a very large version number indeed. You only need to increment the version number (in some way) when you release a new version to the outside world.
So If you make a major change move from version 1.0.0.0 to version 2.0.0.0 (you changed from WinForms to WPF for example). If you make a smaller change move from 1.0.0.0 to 1.1.0.0 (you added support for png files). If you make a minor change then go from 1.0.0.0 to 1.0.1.0 (you fixed some bugs).
If you really want to get detailed use the final number as the build number which would increment for every checkin/commit (but I think that's going too far).
ChrisF♦ChrisFI would use x.y.z kind of versioning
x - major releasey - minor releasez - build number
Mahesh VelagaMahesh VelagaI basically follow this pattern:
start from 0.1.0
when it's ready I branch the code in the source repo, tag 0.1.0 and create the 0.1.0 branch, the head/trunk becomes 0.2.0-snapshot or something similar
I add new features only to the trunk, but backport fixes to the branch and in time I release from it 0.1.1, 0.1.2, ...
I declare version 1.0.0 when the product is considered feature complete and doesn't have major shortcomings
from then on - everyone can decide when to increment the major version...
I use this rule for my applications:
x.y.z
Where:
- x = main version number, 1-~.
- y = feature number, 0-9. Increase this number if the change contains new features with or without bug fixes.
- z = hotfix number, 0-~. Increase this number if the change only contains bug fixes.
Example:
- For new application, the version number starts with 1.0.0.
- If the new version contains only bug fixes, increase the hotfix number so the version number will be 1.0.1.
- If the new version contains new features with or without bug fixes, increase the feature number and reset the hotfix number to zero so the version number will be 1.1.0. If the feature number reaches 9, increase the main version number and reset the feature and hotfix number to zero (2.0.0 etc)
We use a.b.c.d where
- a - major (incremented on delivery to client)
- b - minor (incremented on delivery to client)
- c - revision (incremented on internal releases)
- d - build (incremented by cruise control)
Yet another example for the A.B.C approach is the Eclipse Bundle Versioning. Eclipse bundles rather have a fourth segment:
In Eclipse, version numbers are composed of four (4) segments: 3 integers and a string respectively named major.minor.service.qualifier. Each segment captures a different intent:
- the major segment indicates breakage in the API
- the minor segment indicates 'externally visible' changes
- the service segment indicates bug fixes and the change of development stream
- the qualifier segment indicates a particular build
There is also the date versioning scheme, eg: YYYY.MM , YY.MM , YYYYMMDD
It is quite informative because a first look gives an impression about the release date. But i prefer the x.y.z scheme, because i always want to know a product's exact point in its life cycle (Major.minor.release)
athspkathspkThe basic answer is 'It depends'.
What is your objective in versioning? Many people use version.revision.build and only advertise version.revision to the world as that's a release version rather than a dev version. If you use the check-in 'version' then you'll quickly find that your version numbers become large.
Software Version Control Naming Conventions
If you are planning your project then I'd increment revision for releases with minor changes and increment version for releases with major changes, bug fixes or functionality/features. If you are offering beta or nightly build type releases then extend the versioning to include the build and increment that with every release.
Still, at the end of the day, it's up to you and it has to make sense to you.
LazarusLazarusSoftware Naming Standard
As Mahesh says:I would use x.y.z kind of versioning
x - major releasey - minor releasez - build number
you may want to add a datetime, maybe instead of z.
You increment the minor release when you have another release.The major release will probably stay 0 or 1, you change that when you really make major changes (often when your software is at a point where its not backwards compatible with previous releases, or you changed your entire framework)
SirLenz0rlotSirLenz0rlotYou know you can always check to see what others are doing. Open source software tend to allow access to their repositories. For example you could point your SVN browser to http://svn.doctrine-project.org and take a look at the versioning system used by a real project.
Version numbers, tags, it's all there.
Manos DilaverakisManos DilaverakisWe follow a.b.c approach like:
increament 'a' if there is some major changes happened in application. Like we upgrade .NET 1.1 application to .NET 3.5
increament 'b' if there is some minor changes like any new CR or Enhancement is implemented.
increament 'c' if there is some defects fixes in the code.
I start versioning at the lowest (non hotfix) segement. I do not limit this segment to 10. Unless you are tracking builds then you just need to decide when you want to apply an increment. If you have a QA phase then that might be where you apply an increment to the lowest segment and then the next segement up when it passes QA and is released. Leave the topmost segment for Major behavior/UI changes.
If you are like me you will make it a hybrid of the methods so as to match the pace of your software's progression.
I think the most accepted pattern a.b.c. or a.b.c.d especially if you have QA/Compliance in the mix. I have had so much flack around date being a regular part of versions that I gave it up for mainstream.
I do not track builds so I like to use the a.b.c pattern unless a hotfix is involved. When I have to apply a hotfix then I apply parameter d as a date with time. I adopted the time parameter as d because there is always the potential of several in a day when things really blow up in production. I only apply the d segment (YYYYMMDDHHNN) when I'm diverging for a production fix.
I personally wouldn't be opposed to a software scheme of va.b revc where c is YYYYMMDDHHMM or YYYYMMDD.
All that said. If you can just snag a tool to configure and run with it will keep you from the headache having to marshall the opinion facet of versioning and you can just say 'use the tool'... because everyone in the development process is typically so compliant.