|
Packit |
1470ea |
|
|
Packit |
1470ea |
xmlns:its="http://www.w3.org/2005/11/its"
|
|
Packit |
1470ea |
type="topic"
|
|
Packit |
1470ea |
id="writing-good-code">
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<info>
|
|
Packit |
1470ea |
<link type="guide" xref="index#general-guidelines"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Federico Mena-Quintero</name>
|
|
Packit |
1470ea |
<email its:translate="no">federico@gnome.org</email>
|
|
Packit |
1470ea |
<years>2013</years>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Miguel de Icaza</name>
|
|
Packit |
1470ea |
<email its:translate="no">miguel@gnome.org</email>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Morten Welinder</name>
|
|
Packit |
1470ea |
<email its:translate="no">mortenw@gnome.org</email>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<desc>Good, readable code keeps the project maintainable</desc>
|
|
Packit |
1470ea |
</info>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<title>The Importance of Writing Good Code</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
GNOME is a very ambitious free software project, and it is
|
|
Packit |
1470ea |
composed of many software packages that are more or less
|
|
Packit |
1470ea |
independent of each other. A lot of the work in GNOME is done by
|
|
Packit |
1470ea |
volunteers: although there are many people working on GNOME
|
|
Packit |
1470ea |
full-time or part-time for here, volunteers still make up a large
|
|
Packit |
1470ea |
percentage of our contributors. Programmers may come and go at
|
|
Packit |
1470ea |
any time and they will be able to dedicate different amounts of
|
|
Packit |
1470ea |
time to the GNOME project. People’s “real world” responsibilities
|
|
Packit |
1470ea |
may change, and this will be reflected in the amount of time that
|
|
Packit |
1470ea |
they can devote to GNOME.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Software development takes long amounts of time and painstaking
|
|
Packit |
1470ea |
effort. This is why most part-time volunteers cannot start big
|
|
Packit |
1470ea |
projects by themselves; it is much easier and more rewarding to
|
|
Packit |
1470ea |
contribute to existing projects, as this yields results that are
|
|
Packit |
1470ea |
immediately visible and usable.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Thus, we conclude that it is very important for existing projects
|
|
Packit |
1470ea |
to make it as easy as possible for people to contribute to them.
|
|
Packit |
1470ea |
One way of doing this is by making sure that programs are easy to
|
|
Packit |
1470ea |
read, understand, modify, and maintain.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Messy code is hard to read, and people may lose interest if they
|
|
Packit |
1470ea |
cannot decipher what the code tries to do. Also, it is important
|
|
Packit |
1470ea |
that programmers be able to understand the code quickly so that
|
|
Packit |
1470ea |
they can start contributing with bug fixes and enhancements in a
|
|
Packit |
1470ea |
short amount of time. Source code is a form of
|
|
Packit |
1470ea |
communication, and it is more for people than for
|
|
Packit |
1470ea |
computers. Just as someone would not like to read a novel with
|
|
Packit |
1470ea |
spelling errors, bad grammar, and sloppy punctuation, programmers
|
|
Packit |
1470ea |
should strive to write good code that is easy to understand and
|
|
Packit |
1470ea |
modify by others.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The following are some important qualities of good code:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<terms>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<title>Cleanliness</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Clean code is easy to read with minimum effort. This lets
|
|
Packit |
1470ea |
people start to understand it easily. This includes the
|
|
Packit |
1470ea |
coding style itself (brace placement, indentation, variable
|
|
Packit |
1470ea |
names), and the actual control flow of the code.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<title>Consistency</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Consistent code makes it easy for people to understand how a
|
|
Packit |
1470ea |
program works. When reading consistent code, one
|
|
Packit |
1470ea |
subconsciously forms a number of assumptions and expectations
|
|
Packit |
1470ea |
about how the code works, so it is easier and safer to make
|
|
Packit |
1470ea |
modifications to it. Code that looks the same in two
|
|
Packit |
1470ea |
places should work the same, too.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<title>Extensibility</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
General-purpose code is easier to reuse and modify than very
|
|
Packit |
1470ea |
specific code with lots of hardcoded assumptions. When
|
|
Packit |
1470ea |
someone wants to add a new feature to a program, it will
|
|
Packit |
1470ea |
obviously be easier to do so if the code was designed to be
|
|
Packit |
1470ea |
extensible from the beginning. Code that was not written this
|
|
Packit |
1470ea |
way may lead people into having to implement ugly hacks to add
|
|
Packit |
1470ea |
features.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<title>Correctness</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Finally, code that is designed to be correct lets people spend
|
|
Packit |
1470ea |
less time worrying about bugs, and more time enhancing the
|
|
Packit |
1470ea |
features of a program. Users also appreciate correct code,
|
|
Packit |
1470ea |
since nobody likes software that crashes. Code that is
|
|
Packit |
1470ea |
written for correctness and safety (i.e. code that explicitly
|
|
Packit |
1470ea |
tries to ensure that the program remains in a consistent
|
|
Packit |
1470ea |
state) prevents many kinds of silly bugs.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</terms>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="book-references">
|
|
Packit |
1470ea |
<title>Book References</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<link href="http://www.cc2e.com">Code Complete</link>, by Steve McConnell.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<link href="http://martinfowler.com/books/refactoring.html">
|
|
Packit |
1470ea |
Refactoring: Improving the Design of Existing Code
|
|
Packit |
1470ea |
</link>, by Martin Fowler.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<link href="http://en.wikipedia.org/wiki/Design_Patterns">
|
|
Packit |
1470ea |
Design Patterns: Elements of Reusable Object-Oriented Software
|
|
Packit |
1470ea |
</link>, by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
<link href="http://astore.amazon.com/gnomestore-20/detail/020163385X">
|
|
Packit |
1470ea |
Object-Oriented Design Heuristics
|
|
Packit |
1470ea |
</link>, by Arthur Riel.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
</page>
|