Edit filter log

''''Coding conventions''' are a set of guidelines for a specific [[programming language]] that recommend [[programming style]], practices and methods for each aspect of a piece program written in this language. These conventions usually cover file organization, [[Indent style|indentation]], [[Comment (computer programming)|comments]], [[Declaration (computer science)|declarations]], [[statement (programming)|statements]], [[Whitespace (computer science)|white space]], [[Identifier naming convention|naming conventions]], [[Best Coding Practices|programming practices]], [[:Category:Programming principles|programming principles]], [[:Category:Programming rules of thumb|programming rules of thumb]], architectural best practices, etc. These are guidelines for [[Software_quality_model|software structural quality]]. [[programmer|Software programmers]] are highly recommended to follow these guidelines to help improve the [[readability]] of their [[source code]] and make [[software maintenance]] easier. Coding conventions are only applicable to the human maintainers and [[peer review]]ers of a software project. Conventions may be formalized in a documented set of rules that an entire team or company follows, or may be as informal as the habitual coding practices of an individual. Coding conventions are not enforced by [[compiler]]s. ==Software maintenance== Reducing the cost of [[software maintenance]] is the most often cited reason for following coding conventions. In their introduction to code conventions for the Java programming language, Sun Microsystems provides the following rationale:<ref> {{cite web | title = Code Conventions for the Java Programming Language : Why Have Code Conventions | publisher = Sun Microsystems, Inc. | date = 1999-04-20 | url = http://www.oracle.com/technetwork/java/index-135089.html }} </ref> <blockquote> Code conventions are important to programmers for a number of reasons: *40%–80% of the lifetime cost of a piece of software goes to maintenance. <ref>Robert L. Glass: Facts and Fallacies of Software Engineering; Addison Wesley, 2003. </ref> *Hardly any software is maintained for its whole life by the original author. *Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. *If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create. </blockquote> ===Software engineering=== Software engineering is the process by which the project is specified and designed. It is absolutely fundamental to the success of projects, particularly if they are large projects. The software engineering process is what runs the coding process to successful completion. Good software engineering can make the difference between a successful project - both in financial and engineering terms - and a project that is, at worst, dead on delivery. Good software engineering will minimise downstream costs and maximise the marketing success of the project. ====Project specifications==== The following documents need to be produced: # The project brief. This is what kicks off the project. It is basically a brief description of the project and does not form a part of the formal document chain. # The requirements specification. This specifies what the project is to do. It is the fundamental part of the document chain. All other documents relate to it. # The project design. This is the formal design document of the project. It specifies the modules and the components, what their interfaces are and how they are connected. The software engineer, in carrying out this task, is looking at all the various ways to design the project and is choosing the best ways. He/She is taking into consideration all aspects including technical, quality, managerial, logistical and commercial. This includes time and cost of development, maintenance, support and usage of - both upfront and downstream. Part of this job is the architectural design but it goes a lot farther than that. # The test specification. This specifies all the tests that are to be performed and what results are to be checked for. Often tests are run within automated test harnesses and the tests specified either within code files or script files. # The test results. The project specifications all the way down to the test results form what is called a document chain. Each document has a 1:1 relationship to the previous document. And ultimately the test specification has a 1:1 relationship to the requirements specification. The document chain is bidirectional - specifications going down, results coming back up. These methods are called formal methods. ===Quality=== [[Software peer review]] frequently involves reading source code. This type of peer review is primarily a [[Software bug|defect]] detection activity. By definition, only the original author of a piece of code has read the source file before the code is submitted for review. Code that is written using consistent guidelines is easier for other reviewers to understand and assimilate, improving the efficacy of the defect detection process. Even for the original author, consistently coded software eases maintainability. There is no guarantee that an individual will remember the precise rationale for ''why'' a particular piece of code was written in a certain way long after the code was originally written. Coding conventions can help. Consistent use of [[Whitespace (computer science)|whitespace]] improves readability and reduces the time it takes to understand the software. ====Coding standards==== Where coding conventions have been specifically designed to produce high-quality code, and have then been formally adopted, they then become coding standards. Specific styles, irrespective of whether they are commonly adopted, do not automatically produce good quality code. It is only if they are designed to produce good quality code that they actually result in good quality code being produced, i.e., they must be very logical in every aspect of their design - every aspect justified and resulting in quality code being produced. ====Driving down complexity==== The management of complexity is very important. There is a very basic principle - during the project development ask the question - "has this project been implemented with the least amount of code necessary ?". If it hasn't then unnecessary work has been undertaken and unnecessary cost - both upfront and downstream - has been incurred. This is the "Keep it Simple" rule - simple but effective. Complexity is managed both at the design stage - how the project is architectured - and at the development stage - what coding is used. If the coding is kept basic and simple then the complexity will be minimised. Very often this is keeping the coding as 'physical' as possible - coding in a manner that is very direct and not highly abstract. This produces optimal code that is easy to read and follow. The more complex the code is the more likely it is to be buggy, the more difficult the bugs are to find and the more likely there are to be hidden bugs. Safe coding is very important. ===Refactoring=== [[Refactoring]] refers to a software maintenance activity where [[source code]] is modified to improve readability or improve its structure. Software is often refactored to bring it into conformance with a team's stated coding standards after its initial release. Any change that does not alter the behavior of the software can be considered refactoring. Common refactoring activities are changing variable names, [[Rename Method|renaming methods]], moving methods or whole classes and [[Extract Method|breaking large methods]] (or [[Function (programming)|function]]s) into smaller ones. [[agile software development|Agile software development methodologies]] plan for regular (or even continuous) refactoring making it an integral part of the team [[software development process]].<ref> {{cite web | last = Jeffries | first = Ron | title = What is Extreme Programming? : Design Improvement | publisher = XP Magazine | date = 2001-11-08 | url = http://www.xprogramming.com/xpmag/whatisxp.htm#design }} </ref> ==Task automation== Coding conventions allow to have simple scripts or programs whose job is to process source code for some purpose other than compiling it into an executable. It is common practice to count the software size ([[Source lines of code]]) to track current project progress or establish a baseline for future [[Estimation in software engineering|project estimates]]. Consistent coding standards can, in turn, make the measurements more consistent. Special [[Tag (metadata)|tag]]s within [[source code comment]]s are often used to process documentation, two notable examples are [[javadoc]] and [[doxygen]]. The tools specify the use of a set of tags, but their use within a project is determined by convention. Coding conventions simplify writing new software whose job is to process existing software. Use of [[static code analysis]] has grown consistently since the 1950s. Some of the growth of this class of development tools stems from increased maturity and sophistication of the practitioners themselves (and the modern focus on [[Safety-critical#Software_engineering_for_life-critical_systems|safety]] and [[Vulnerability (computing)|security]]), but also from the nature of the languages themselves. ==Language factors== All software practitioners must grapple with the problems of organizing and managing very many detailed instructions, each of which will eventually be processed in order to perform the task for which it was written. For all but the smallest software projects, source code (instructions) are partitioned into separate [[Computer file|files]] and frequently among many [[File directory|directories]]. It was natural for programmers to collect closely related functions (behaviors) in the same file and to collect related files into directories. As software development shifted from purely [[procedural programming]] (such as found in [[FORTRAN]]) towards more [[Object-oriented programming|object-oriented]] constructs (such as found in [[C++]]), it became the practice to write the code for a single (public) class in a single file (the 'one class per file' convention).<ref> {{cite web | last = Hoff | first = Todd | title = C++ Coding Standard : Naming Class Files | date = 2007-01-09 | url = http://www.possibility.com/Cpp/CppCodingStandard.html#cflayout }} </ref><ref>[http://wiki.fifengine.de/index.php?title=Coding_standards FIFE coding standards]</ref> Java has gone one step further - the Java compiler returns an error if it finds more than one public class per file. A convention in one language may be a requirement in another. Language conventions also affect individual source files. Each compiler (or interpreter) used to process source code is unique. The rules a compiler applies to the source creates implicit standards. For example, Python code is much more consistently indented than, say Perl, because whitespace (indentation) is actually significant to the interpreter. Python does not use the brace syntax Perl uses to delimit functions. Changes in indentation serve as the delimiters.<ref> {{cite web | last = van Rossum | first = Guido |editor=Fred L. Drake, Jr | title = Python Tutorial : First Steps Towards Programming | publisher = Python Software Foundation | date = 2006-09-19 | url = https://docs.python.org/tut/node5.html#SECTION005200000000000000000 }} </ref><ref> {{cite web | last = Raymond | first = Eric | title = Why Python? | publisher = Linux Journal | date = 2000-05-01 | url = http://www.linuxjournal.com/article/3882 }} </ref> Tcl, which uses a brace syntax similar to Perl or C/C++ to delimit functions, does not allow the following, which seems fairly reasonable to a C programmer: <source lang="tcl"> set i 0 while {$i < 10} { puts "$i squared = [expr $i*$i]" incr i } </source> The reason is that in Tcl, curly braces are not used only to delimit functions as in C or Java. More generally, curly braces are used to group words together into a single argument.<ref> {{cite web | last = Tcl Developer Xchange | title = Summary of Tcl language syntax | publisher = ActiveState | url = http://www.tcl.tk/man/tcl8.4/TclCmd/Tcl.htm }} </ref><ref> {{cite web | last = Staplin | first = George Peter | title = Why can I not start a new line before a brace group | publisher = 'the Tcler's Wiki' | date = 2006-07-16 | url = http://wiki.tcl.tk/8344 }} </ref> In Tcl, the ''word'' '''while''' takes two arguments, a ''condition'' and an ''action''. In the example above, '''while''' is missing its second argument, its ''action'' (because the Tcl also uses the newline character to delimit the end of a command). ==Common conventions== {{wikibooks|Computer Programming/Coding Style}} There are a large number of coding conventions; see ''[[b:Computer Programming/Coding Style|Coding Style]]'' for numerous examples and discussion. Common coding conventions may cover the following areas: * [[Comment (computer programming)|Comment]] conventions * [[Indent style]] conventions * [[Characters per line|Line length]] conventions * [[Naming convention (programming)|Naming]] conventions * [[Best Coding Practices|Programming practices]] * [[:Category:Programming principles|Programming principles]] * [[:Category:Programming rules of thumb|Programming rules of thumb]] * [[Programming style]] conventions * Programming level coding applications ==See also== *[[Comparison of programming languages (syntax)]] *[[Indent style]] *[[List of tools for static code analysis]] *[[MISRA C]] *[[Programming style]] *[[Hungarian Notation]] ==References== {{reflist}} ==External links== ===Coding conventions for languages=== {{wikibooks|Ada Style Guide}} *ActionScript: [http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions Flex SDK coding conventions and best practices] *Ada: [http://www.adaic.com/docs/95style/html/cover.html Ada 95 Quality and Style Guide: Guidelines for Professional Programmers] *Ada: [http://www.dit.upm.es/ork/documents/adahis.pdf Guide for the use of the Ada programming language in high integrity systems] (ISO/IEC TR 15942:2000) *Ada: [http://software.gsfc.nasa.gov/AssetsApproved/PA2.4.1.1.1.pdf NASA Flight Software Branch &mdash; Ada Coding Standard] *Ada: [ftp://ftp.estec.esa.nl/pub/wm/wme/bssc/bssc983.pdf European Space Agency's Ada Coding Standard] (BSSC(98)3) *C: [http://www.ganssle.com/fsm.pdf Ganssle Group's Firmware Development Standard] *C: [http://www.netrino.com/Coding-Standard Netrino Embedded C Coding Standard] *C: [http://micrium.com/download/an2000.pdf Micrium C Coding Standard (dead link)] *C: [https://www.securecoding.cert.org/confluence/display/c/SEI+CERT+C+Coding+Standard SEI CERT C Coding Standard] *C++: [http://www.state-machine.com/doc/AN_QL_Coding_Standard.pdf Quantum Leaps C/C++ Coding Standard] *C++: [[b:C++ Programming/Programming Languages/C++/Code/Style Conventions|C++ Programming/Programming Languages/C++/Code/Style Conventions]] *C++: [http://geosoft.no/development/cppstyle.html GeoSoft's C++ Programming Style Guidelines] *C++: [http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml Google's C++ Style Guide] *C++: [[High Integrity C++]] *C#: [https://msdn.microsoft.com/en-us/library/ff926074.aspx C# Coding Conventions (C# Programming Guide)] *C#: [http://msdn.microsoft.com/en-us/library/ms229042(VS.80).aspx Design Guidelines for Developing Class Libraries] *C#: [http://blogs.msdn.com/brada/articles/361363.aspx Brad Abrams] *C#: [http://www.tiobe.com/standards/gemrcsharpcs.pdf Philips Healthcare] *D: [http://www.digitalmars.com/d/1.0/dstyle.html The D Style] *Dart: [https://www.dartlang.org/articles/style-guide The Dart Style Guide] *Erlang: [http://www.erlang.se/doc/programming_rules.shtml Erlang Programming Rules and Conventions] *Flex: [http://sourceforge.net/adobe/flexsdk/wiki/Coding%20Conventions/ Code conventions for the Flex SDK] *Java: [http://www.ambysoft.com/essays/javaCodingStandards.html Ambysoft's Coding Standards for Java] *Java: [http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html Code Conventions for the Java Programming Language] *Java: [http://geosoft.no/development/javastyle.html GeoSoft's Java Programming Style Guidelines] *Java: {{dmoz|/Computers/Programming/Languages/Java/Coding_Standards/|Java Coding Standards}} *Java: [http://www.softwaremonkey.org/Article/Computer/Coding-Standards SoftwareMonkey's Coding Standards for Java and other C-like languages] Java: [http://www.logicheart.com/Coding Standards for Java language] *JavaScript: [http://javascript.crockford.com/code.html Code Conventions for the JavaScript Programming Language] *Lisp: [http://mumble.net/~campbell/scheme/style.txt Riastradh's Lisp Style Rules] *MATLAB: [http://computersandbuildings.com/matlab-coding-conventions/ Neurobat Coding Conventions for MATLAB] *Mono: [http://www.mono-project.com/Coding_Guidelines Programming style for Mono] *Object Pascal: [http://edn.embarcadero.com/article/10280 Object Pascal Style Guide] *Perl: [http://perldoc.perl.org/perlstyle.html Perl Style Guide] *PHP::PEAR: [http://pear.php.net/manual/en/standards.php PHP::PEAR Coding Standards] *PHP::FIG: [http://www.php-fig.org/ PHP Framework Interop Group] *Python: [https://www.python.org/peps/pep-0008.html Style Guide for Python Code] *Ruby: [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide] *Ruby: [https://github.com/styleguide/ruby GitHub Ruby style guide] ===Coding conventions for projects=== *[http://httpd.apache.org/dev/styleguide.html Apache Developers' C Language Style Guide] *[http://drupal.org/coding-standards Drupal PHP Coding Standards] *[http://framework.zend.com/manual/1.12/en/coding-standard.html Zend Framework Coding Standards] *[[GNU Coding Standards]] *[https://code.google.com/p/google-styleguide/ Style guides for Google-originated open-source projects] *[http://lxr.linux.no/source/Documentation/CodingStyle Linux Kernel Coding Style] (or Documentation/CodingStyle in the Linux Kernel source tree) *[http://moduliq.org/documentation/moduliq_zero_indent_coding_style.html ModuLiq Zero Indent Coding Style] *[https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style Mozilla Coding Style Guide] *[http://www.qhull.org/road/road-faq/xml/cpp-guideline.xml Road Intranet's C++ Guidelines] *[ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/src/share/misc/style The NetBSD source code style guide] (formerly known as the BSD Kernel Normal Form) *[http://www.openbsd.org/cgi-bin/man.cgi?query=style&sektion=9 OpenBSD Kernel source file style guide (KNF)] *{{cite web | title = GNAT Coding Style: A Guide for GNAT Developers | work = GCC online documentation | publisher = Free Software Foundation | url = http://gcc.gnu.org/onlinedocs/gnat-style/ | accessdate = 2009-01-19 }} ([http://gcc.gnu.org/onlinedocs/gnat-style.pdf PDF]) *[http://rfc.zeromq.org/spec:21 ZeroMQ C Language Style for Scalability (CLASS)] [[Category:Source code]]'