Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:53:55Z

Veovis: /* Naming Convention */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== [http://en.wikipedia.org/wiki/Whitespace Whitespace] ===

Appropriate use of blank lines and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names ''userIdentifcationValue'' and ''userID'' are both fairly descriptive but ''userID'' is shorter and easier to type and is just as clear as ''userIdentifcationValue''. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good [http://en.wikipedia.org/wiki/Object_oriented object oriented] design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the details of drawing lines. The extra code makes it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and makes it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:53:34Z

Veovis: /* Naming Convention */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== [http://en.wikipedia.org/wiki/Whitespace Whitespace] ===

Appropriate use of blank lines and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but ''userID'' is shorter and easier to type and is just as clear as ''userIdentifcationValue''. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good [http://en.wikipedia.org/wiki/Object_oriented object oriented] design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the details of drawing lines. The extra code makes it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and makes it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:52:36Z

Veovis: /* Code Structure and Comments */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== [http://en.wikipedia.org/wiki/Whitespace Whitespace] ===

Appropriate use of blank lines and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good [http://en.wikipedia.org/wiki/Object_oriented object oriented] design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the details of drawing lines. The extra code makes it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and makes it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:50:55Z

Veovis: /* Whitespace */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== [http://en.wikipedia.org/wiki/Whitespace Whitespace] ===

Appropriate use of blank lines and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good [http://en.wikipedia.org/wiki/Object_oriented object oriented] design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:50:17Z

Veovis: /* Code Structure and Comments */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good [http://en.wikipedia.org/wiki/Object_oriented object oriented] design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:41:57Z

Veovis: /* Naming Conventions and Style Guides */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [http://www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:41:37Z

Veovis:

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

== Naming Conventions and Style Guides ==

''' C/C++ '''
* [http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx Hungarian Notation]
* [http://geosoft.no/development/cppstyle.html C++ Programming Style Guidelines]

''' C# '''
* [www.sourceformat.com/pdf/cs-coding-standard-bellware.pdf C# Code Style Guide]

''' Java '''
* [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Code Conventions for the Java Programming Language]

''' Perl '''
* [http://www.perl.com/doc/manual/html/pod/perlstyle.html Perl style guide ]

''' PHP '''
* [http://wshell.wordpress.com/2009/10/02/ PHP Good Practices 1 – Naming Conventions]

''' Ruby '''
* [http://www.caliban.org/ruby/rubyguide.shtml The Unofficial Ruby Usage Guide]

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:33:40Z

Veovis: /* Naming Convention */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g(m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:32:43Z

Veovis: /* Naming Convention */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g( m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex(
m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:30:46Z

Veovis: /* Naming Convention */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

''' Example 1 '''
<pre>
void ML::d(const Canvas *vc,
TS* ts,
PointType tb,
PointType to,
RectangleType dr)
{
Int16 sdx = dr.tl.x - to.x;
Int16 sdy = dr.tl.y - to.y;

for(UInt16 x = tb.x; x < m_ms.x; x++)
{
for(UInt16 y = tb.y; y < m_mapSize.y; y++)
{
T* t = ts->g( m_lb[(x * m_ms.y) + y]);
if(t)
t->d(vc, sdx, sdy);

sdy += ts->gh();

if(sdy >= dr.tl.y + dr.e.y)
break;
}

sdy = dr.tl.y - to.y;
sdx += ts->gw();

if(sdx >= dr.tl.x + dr.e.x)
break;
}
}
</pre>

''' Example 2 '''
<pre>
void MapLayer::draw(const Canvas *viewportCanvas,
TileSet* tset,
PointType tileBegin,
PointType tileOffset,
RectangleType drawRect)
{
Int16 screenDrawX = drawRect.topLeft.x - tileOffset.x;
Int16 screenDrawY = drawRect.topLeft.y - tileOffset.y;

for(UInt16 x = tileBegin.x; x < m_mapSize.x; x++)
{
for(UInt16 y = tileBegin.y; y < m_mapSize.y; y++)
{
Tile* tile = tset->getTileAtIndex( m_layerBytes[(x * m_mapSize.y) + y]);
if(tile)
tile->draw(viewportCanvas, screenDrawX, screenDrawY);

screenDrawY += tset->getTileHeight();

if(screenDrawY >= drawRect.topLeft.y + drawRect.extent.y)
break;
}

screenDrawY = drawRect.topLeft.y - tileOffset.y;
screenDrawX += tset->getTileWidth();

if(screenDrawX >= drawRect.topLeft.x + drawRect.extent.x)
break;
}
}
</pre>

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:19:50Z

Veovis: /* Whitespace */

'''Self-Documenting Code'''

== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

''' Example 1 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {return;}
// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();
if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);
// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

''' Example 2 '''
<pre>
// only draw if we have good values
if (Double.isNaN(transX0) || Double.isNaN(transY0)
|| Double.isNaN(transX1) || Double.isNaN(transY1)) {
return;
}

// create a line to use to determine where the threshold is crossed
Line2D.Double tline = new Line2D.Double();

if (orientation == PlotOrientation.HORIZONTAL)
tline.setLine(threshY0,threshX0,threshY1,threshX1);
else if (orientation == PlotOrientation.VERTICAL)
tline.setLine(threshX0,threshY0,threshX1,threshY1);

// calculate the point where the threshold is crossed
Point2D.Double tintersect = lineIntersection(tline,state.workingLine);
if (tintersect == null)
return;
</pre>

The second example is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

[BAD EXAMPLE]
[GOOD EXAMPLE]

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

''' Example 1 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(thresholdPaint));
g2.draw(shape);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
g2.setStroke(getItemStroke(series, item));
g2.setPaint(getItemPaint(series, item));
g2.draw(shape);
}
}
</pre>
''' Example 2 '''
<pre>
protected void drawLine() {
// ** SNIP **

// determine whether the line starts above or below the threshold
if (y1>y0) {
// line starts below the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);
}
else {
// line starts above the threshold
state.workingLine.setLine(transX0, transY0, tintersect.getX(),
tintersect.getY());
drawFirstPassShape(g2, pass, series, item, state.workingLine, true);

state.workingLine.setLine(tintersect.getX(), tintersect.getY(),
transX1, transY1);
drawFirstPassShape(g2, pass, series, item, state.workingLine, false);
}
}

protected void drawFirstPassShape(Graphics2D g2, int pass, int series,
int item, Shape shape, boolean overthreshold) {
g2.setStroke(getItemStroke(series, item));

if (overthreshold==true)
g2.setPaint(thresholdPaint);
else
g2.setPaint(getItemPaint(series, item));

g2.draw(shape);
}
</pre>

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:17:00Z

Veovis:

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:15:26Z

Veovis:

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:13:29Z

Veovis:

CSC/ECE 517 Fall 2009/wiki3 13 is

2009-11-11T00:12:19Z

Veovis:

= Self-Documenting Code =
== Introduction ==
One of the characteristics of elegant, well-designed code is that it should be easy for someone to read the code and understand exactly what the code does. It should be possible to understand the code by using the names and comments within the code without needing any additional documentation. Source code that is easy to read and understand is known as self-documenting code.

There are numerous advantages to self-documenting code. One of the biggest advantages is the fact that it is often quite easy to maintain or extend code that is self-documenting. Another advantage is the fact that it is not essential to have external sources of documentation to understand how the code works. Self-documentation can also help prevent certain types of bugs or defects from being introduced in the code due to the fact that developers usually have a clearer understanding of what the code does.

== Techniques ==

By following a few simple techniques and guidelines developers can produce self-documenting code fairly easily.

=== Whitespace ===

Appropriate use of blank lines between and indentation can greatly improve the readability of source code. Blank lines should be inserted between logical sections or blocks of code. In most languages code contained within a block should be indented to make it clear that it is part of a block of code. Consider the following examples:

[BAD CODE EXAMPLE]
[GOOD CODE EXAMPLE]

Example B is much easier to read because of the proper use of whitespace. It is usually best to avoid putting more than one statement of code on a single line unless the statements are very short and very simple. Long statements can (and should) be broken into multiple lines with indentation to indicate that the additional lines belong to the same statement.

Some languages have style guidelines that describe where and when whitespace should be used, such has which lines of a method should be indented and where block identifiers such as { or } should be located. Links to style guidelines for various languages are included below.

=== Naming Convention ===

Choosing good names is critical to writing self-documenting code. In many languages objects, variables, and methods are identified by their name. Good code uses names that are clear and descriptive. Descriptive names do not have to be long or verbose and it is often better to use shorter names with logical abbreviations instead of a really long name. For instance, the variable names “userIdentifcationValue” and “userID” are both fairly descriptive but “userID” is shorter and easier to type and is just as clear as “userIdentifcationValue”. Bad code uses names that are generic or that provide no indication what the item is used for such as i, j, n, num, r, x, or cv. Consider the following examples:

[BAD EXAMPLE]
[GOOD EXAMPLE]

It is very difficult to figure out what the first code section does because none of the variables, objects, or methods have descriptive names. The second code section uses descriptive names and is much easier to read and understand.

Many programming languages have established naming conventions that are used to distinguish a variable from an object or a method. It is important for a programmer to follow the established naming convention for the language that he or she is writing in. Links to naming conventions for various languages are included below.

=== Code Structure and Comments ===

There are often many different ways of writing code to accomplishing a particular task. Generally a simple approach to a problem produces code that is more readable and easier to understand than a complex solution.

Some complex algorithms can be greatly simplified by moving pieces of code into separate methods or functions. Code that has well defined methods generally exhibits good object oriented design in addition to being easier to understand and maintain. Consider the following examples:

[BAD EXAMPLE]
[GOOD EXAMPLE]

The first example has a lot of code to handle the process of drawing lines making it harder to understand what else the code is doing. The second example moves the task of drawing the lines to a separate drawing method which helps simplify the code and make it easier to follow.

Generally the simpler the code is, the easier it is to understand it. When given the choice between a simple implementation and a complex one the simpler implementation will almost always be easier to debug and maintain.

Some coding problems are very difficult to solve in a straightforward, easy to understand manner. In these situations it is important to thoroughly document the code with comments that explain exactly what is being done and how. In some cases it is also a good idea to include comments that describe why the section was implemented the way it is.

CSC/ECE 517 Fall 2009/wiki2 7 ov

2009-10-07T13:36:59Z

Veovis: /* Ruby - Mixins and Modules */

'''Survey of Language Features for Code Reuse'''

== Direct inclusion ==
Code can be reused by simply storing it in a defined location and allowing a compiler or preprocessor to insert a copy of the code whenever it is referenced. This is the simplest form of code reuse and is present in many languages.

=== Assembly Language - Macros ===

Many assemblers have support for macros. A macro is a block of code that can be called from any location in the program. A macro can contain any number of instructions and is given a unique name. Some assemblers also support passing various parameters to a macro which can be inserted into the code block contained in the macro.

Within a program the assembler replaces all references to the macro's name with the block of code that the macro represents. Essentially macros allow the programmer to give a chunk of code a name and then use it multiple times within a program or even in many programs.

=== C/C++ - Includes ===

The languages C and C++ had a directive named #include which instructs the compiler to insert the contents of a file into the current source file. Typically a program will use this feature to allow certain functions and macros to be used within multiple source files or in multiple programs.

Used in this way, the [http://en.wikipedia.org/wiki/Function_prototype prototype] for a function would be placed in a file and the file that includes the source code to the function and any file that contains source code using the function will use #include to reference the file containing the function prototype. This allows the compiler to reference the source code to the function wherever it happens to be called.

=== Ruby - Mixins and Modules ===

Ruby has several different features that can be used individually or together to allow a programmer to reuse sections of code. One such feature is known as a module. A module contains a block of code and places it underneath a defined name (or namespace). Variables, classes, and functions within a module can be used by referencing the module name followed by a . and then the name of the item in the module.

For instance, if there is a module named Square which contains a function called draw it can be called by writing:
<pre>
Square.draw()
</pre>
If a module is referenced within a class definition that module is often referred to as a mixin. Any functions or variables that are defined in the module can be used within the class just as if it was defined directly within the class. For instance a module may define methods that are used in several different classes. Each class that needs one of the methods in the module can include the module as a mixin.

A module can be referenced in a class or program by using either the load or require statements. If the load statement is used the module will be coped into the location of the statement much like an Assembly language macro or a C or C++ include.

If the require statement is used then only one copy of the module is loaded into memory. If the module is changed during runtime all parts of the program using that module see the change immediately since they are all using the same chunk of code in memory.

Because of this property modules in Ruby can act like a direct inclusion or a collection of classes.

== Collections of Classes ==
In some object oriented languages code can be reused by grouping certain classes together under a single name. These collections are known by different names in different languages but they all typically provide a way to reference a particular class within a collection even if a class with the same name may be found in a different collection.

=== Java - Packages ===

Java allows [http://en.wikipedia.org/wiki/Class_(computer_science) classes] to be grouped into a collection known as a package. A program can then reference the package and use the classes defined within it or reference a particular class in a package.

Each package is given a unique name and each class in a package can be referenced by giving the name of the package followed by the name of the class like this:
<pre>
java.util.Date somedate = new java.util.Date();
</pre>

=== .NET - Components and Namespaces ===

Microsoft's .NET family of languages allows a class or a group of classes to be compiled into a component. Components typically need to be compiled into a binary [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] containing [http://en.wikipedia.org/wiki/Common_Language_Runtime CLR] code.

Programs can use a component by adding a reference the DLL containing the component's code . Classes contained within a component can then be used just as if the classes were defined directly in the program.

The .NET languages also support a feature called [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespaces] which allows classes to be referenced by a fully qualified name much like Ruby's modules or Java packages. For more complicated designs, a namespace can be nested within another namespace like this:

<pre>
namespace Shape
{
namespace TwoDimensional
{
public class Square
{
}

public class Circle
{
}
}

namespace ThreeDimensional
{
public class Cube
{
}
}
}
</pre>
In this case the class Circle could be referenced from another program by placing the Shape namespace into a component and calling:

Shape.TwoDimensional.Circle myCircle = new Shape.TwoDimensional.Circle();

== Comparison ==

Languages that use a form of direct inclusion often make it very easy to reuse any particular block of code in multiple applications or even within the same application. The principal is a very simple one and is usually quite easy to implement in any given language. However, most forms of direct inclusion do not provide a way to avoid conflicts when multiple variables, functions, routines, classes, or methods share the same name.

Languages that group classes into self-contained collections provide a fairly elegant way to avoid name collisions because each class can be referenced using a fully qualified name that includes the name of the collection it is in. They may not be quite as simple or as easy to use as most forms of direct inclusion but the ability to avoid namespace collisions is often worth it. It is also often easier to determine which collection/package/component a class belongs to than it is to determine which included file contains the class in a direct inclusion system which can aid in debugging and troubleshooting problems.

== References ==
* [http://en.wikipedia.org/wiki/Assembly_language#Macros Assembly language]

* [http://en.wikipedia.org/wiki/Header_file Header file]
* [http://msdn.microsoft.com/en-us/library/36k2cdd4(VS.80).aspx The #include Directive]

* [http://www.rubycentral.com/pickaxe/tut_modules.html Programming Ruby Modules and Mixins]

* [http://en.wikipedia.org/wiki/Java_package Java package]

* [http://msdn.microsoft.com/en-us/library/ms973807.aspx Creating Components in .NET]
* [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespace (C# Reference)]

CSC/ECE 517 Fall 2009/wiki2 7 ov

2009-10-07T13:36:48Z

Veovis: /* Java - Packages */

'''Survey of Language Features for Code Reuse'''

== Direct inclusion ==
Code can be reused by simply storing it in a defined location and allowing a compiler or preprocessor to insert a copy of the code whenever it is referenced. This is the simplest form of code reuse and is present in many languages.

=== Assembly Language - Macros ===

Many assemblers have support for macros. A macro is a block of code that can be called from any location in the program. A macro can contain any number of instructions and is given a unique name. Some assemblers also support passing various parameters to a macro which can be inserted into the code block contained in the macro.

Within a program the assembler replaces all references to the macro's name with the block of code that the macro represents. Essentially macros allow the programmer to give a chunk of code a name and then use it multiple times within a program or even in many programs.

=== C/C++ - Includes ===

The languages C and C++ had a directive named #include which instructs the compiler to insert the contents of a file into the current source file. Typically a program will use this feature to allow certain functions and macros to be used within multiple source files or in multiple programs.

Used in this way, the [http://en.wikipedia.org/wiki/Function_prototype prototype] for a function would be placed in a file and the file that includes the source code to the function and any file that contains source code using the function will use #include to reference the file containing the function prototype. This allows the compiler to reference the source code to the function wherever it happens to be called.

=== Ruby - Mixins and Modules ===

Ruby has several different features that can be used individually or together to allow a programmer to reuse sections of code. One such feature is known as a module. A module contains a block of code and places it underneath a defined name (or namespace). Variables, classes, and functions within a module can be used by referencing the module name followed by a . and then the name of the item in the module.

For instance, if there is a module named Square which contains a function called draw it can be called by writing:

Square.draw()

If a module is referenced within a class definition that module is often referred to as a mixin. Any functions or variables that are defined in the module can be used within the class just as if it was defined directly within the class. For instance a module may define methods that are used in several different classes. Each class that needs one of the methods in the module can include the module as a mixin.

A module can be referenced in a class or program by using either the load or require statements. If the load statement is used the module will be coped into the location of the statement much like an Assembly language macro or a C or C++ include.

If the require statement is used then only one copy of the module is loaded into memory. If the module is changed during runtime all parts of the program using that module see the change immediately since they are all using the same chunk of code in memory.

Because of this property modules in Ruby can act like a direct inclusion or a collection of classes.

== Collections of Classes ==
In some object oriented languages code can be reused by grouping certain classes together under a single name. These collections are known by different names in different languages but they all typically provide a way to reference a particular class within a collection even if a class with the same name may be found in a different collection.

=== Java - Packages ===

Java allows [http://en.wikipedia.org/wiki/Class_(computer_science) classes] to be grouped into a collection known as a package. A program can then reference the package and use the classes defined within it or reference a particular class in a package.

Each package is given a unique name and each class in a package can be referenced by giving the name of the package followed by the name of the class like this:
<pre>
java.util.Date somedate = new java.util.Date();
</pre>

=== .NET - Components and Namespaces ===

Microsoft's .NET family of languages allows a class or a group of classes to be compiled into a component. Components typically need to be compiled into a binary [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] containing [http://en.wikipedia.org/wiki/Common_Language_Runtime CLR] code.

Programs can use a component by adding a reference the DLL containing the component's code . Classes contained within a component can then be used just as if the classes were defined directly in the program.

The .NET languages also support a feature called [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespaces] which allows classes to be referenced by a fully qualified name much like Ruby's modules or Java packages. For more complicated designs, a namespace can be nested within another namespace like this:

<pre>
namespace Shape
{
namespace TwoDimensional
{
public class Square
{
}

public class Circle
{
}
}

namespace ThreeDimensional
{
public class Cube
{
}
}
}
</pre>
In this case the class Circle could be referenced from another program by placing the Shape namespace into a component and calling:

Shape.TwoDimensional.Circle myCircle = new Shape.TwoDimensional.Circle();

== Comparison ==

Languages that use a form of direct inclusion often make it very easy to reuse any particular block of code in multiple applications or even within the same application. The principal is a very simple one and is usually quite easy to implement in any given language. However, most forms of direct inclusion do not provide a way to avoid conflicts when multiple variables, functions, routines, classes, or methods share the same name.

Languages that group classes into self-contained collections provide a fairly elegant way to avoid name collisions because each class can be referenced using a fully qualified name that includes the name of the collection it is in. They may not be quite as simple or as easy to use as most forms of direct inclusion but the ability to avoid namespace collisions is often worth it. It is also often easier to determine which collection/package/component a class belongs to than it is to determine which included file contains the class in a direct inclusion system which can aid in debugging and troubleshooting problems.

== References ==
* [http://en.wikipedia.org/wiki/Assembly_language#Macros Assembly language]

* [http://en.wikipedia.org/wiki/Header_file Header file]
* [http://msdn.microsoft.com/en-us/library/36k2cdd4(VS.80).aspx The #include Directive]

* [http://www.rubycentral.com/pickaxe/tut_modules.html Programming Ruby Modules and Mixins]

* [http://en.wikipedia.org/wiki/Java_package Java package]

* [http://msdn.microsoft.com/en-us/library/ms973807.aspx Creating Components in .NET]
* [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespace (C# Reference)]

CSC/ECE 517 Fall 2009/wiki2 7 ov

2009-10-07T13:36:35Z

Veovis: /* .NET - Components and Namespaces */

'''Survey of Language Features for Code Reuse'''

== Direct inclusion ==
Code can be reused by simply storing it in a defined location and allowing a compiler or preprocessor to insert a copy of the code whenever it is referenced. This is the simplest form of code reuse and is present in many languages.

=== Assembly Language - Macros ===

Many assemblers have support for macros. A macro is a block of code that can be called from any location in the program. A macro can contain any number of instructions and is given a unique name. Some assemblers also support passing various parameters to a macro which can be inserted into the code block contained in the macro.

Within a program the assembler replaces all references to the macro's name with the block of code that the macro represents. Essentially macros allow the programmer to give a chunk of code a name and then use it multiple times within a program or even in many programs.

=== C/C++ - Includes ===

The languages C and C++ had a directive named #include which instructs the compiler to insert the contents of a file into the current source file. Typically a program will use this feature to allow certain functions and macros to be used within multiple source files or in multiple programs.

Used in this way, the [http://en.wikipedia.org/wiki/Function_prototype prototype] for a function would be placed in a file and the file that includes the source code to the function and any file that contains source code using the function will use #include to reference the file containing the function prototype. This allows the compiler to reference the source code to the function wherever it happens to be called.

=== Ruby - Mixins and Modules ===

Ruby has several different features that can be used individually or together to allow a programmer to reuse sections of code. One such feature is known as a module. A module contains a block of code and places it underneath a defined name (or namespace). Variables, classes, and functions within a module can be used by referencing the module name followed by a . and then the name of the item in the module.

For instance, if there is a module named Square which contains a function called draw it can be called by writing:

Square.draw()

If a module is referenced within a class definition that module is often referred to as a mixin. Any functions or variables that are defined in the module can be used within the class just as if it was defined directly within the class. For instance a module may define methods that are used in several different classes. Each class that needs one of the methods in the module can include the module as a mixin.

A module can be referenced in a class or program by using either the load or require statements. If the load statement is used the module will be coped into the location of the statement much like an Assembly language macro or a C or C++ include.

If the require statement is used then only one copy of the module is loaded into memory. If the module is changed during runtime all parts of the program using that module see the change immediately since they are all using the same chunk of code in memory.

Because of this property modules in Ruby can act like a direct inclusion or a collection of classes.

== Collections of Classes ==
In some object oriented languages code can be reused by grouping certain classes together under a single name. These collections are known by different names in different languages but they all typically provide a way to reference a particular class within a collection even if a class with the same name may be found in a different collection.

=== Java - Packages ===

Java allows [http://en.wikipedia.org/wiki/Class_(computer_science) classes] to be grouped into a collection known as a package. A program can then reference the package and use the classes defined within it or reference a particular class in a package.

Each package is given a unique name and each class in a package can be referenced by giving the name of the package followed by the name of the class like this:

java.util.Date somedate = new java.util.Date();

=== .NET - Components and Namespaces ===

Microsoft's .NET family of languages allows a class or a group of classes to be compiled into a component. Components typically need to be compiled into a binary [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] containing [http://en.wikipedia.org/wiki/Common_Language_Runtime CLR] code.

Programs can use a component by adding a reference the DLL containing the component's code . Classes contained within a component can then be used just as if the classes were defined directly in the program.

The .NET languages also support a feature called [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespaces] which allows classes to be referenced by a fully qualified name much like Ruby's modules or Java packages. For more complicated designs, a namespace can be nested within another namespace like this:

<pre>
namespace Shape
{
namespace TwoDimensional
{
public class Square
{
}

public class Circle
{
}
}

namespace ThreeDimensional
{
public class Cube
{
}
}
}
</pre>
In this case the class Circle could be referenced from another program by placing the Shape namespace into a component and calling:

Shape.TwoDimensional.Circle myCircle = new Shape.TwoDimensional.Circle();

== Comparison ==

Languages that use a form of direct inclusion often make it very easy to reuse any particular block of code in multiple applications or even within the same application. The principal is a very simple one and is usually quite easy to implement in any given language. However, most forms of direct inclusion do not provide a way to avoid conflicts when multiple variables, functions, routines, classes, or methods share the same name.

Languages that group classes into self-contained collections provide a fairly elegant way to avoid name collisions because each class can be referenced using a fully qualified name that includes the name of the collection it is in. They may not be quite as simple or as easy to use as most forms of direct inclusion but the ability to avoid namespace collisions is often worth it. It is also often easier to determine which collection/package/component a class belongs to than it is to determine which included file contains the class in a direct inclusion system which can aid in debugging and troubleshooting problems.

== References ==
* [http://en.wikipedia.org/wiki/Assembly_language#Macros Assembly language]

* [http://en.wikipedia.org/wiki/Header_file Header file]
* [http://msdn.microsoft.com/en-us/library/36k2cdd4(VS.80).aspx The #include Directive]

* [http://www.rubycentral.com/pickaxe/tut_modules.html Programming Ruby Modules and Mixins]

* [http://en.wikipedia.org/wiki/Java_package Java package]

* [http://msdn.microsoft.com/en-us/library/ms973807.aspx Creating Components in .NET]
* [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespace (C# Reference)]

CSC/ECE 517 Fall 2009/wiki2 7 ov

2009-10-07T13:30:15Z

Veovis: /* Collections of Classes */

'''Survey of Language Features for Code Reuse'''

== Direct inclusion ==
Code can be reused by simply storing it in a defined location and allowing a compiler or preprocessor to insert a copy of the code whenever it is referenced. This is the simplest form of code reuse and is present in many languages.

=== Assembly Language - Macros ===

Many assemblers have support for macros. A macro is a block of code that can be called from any location in the program. A macro can contain any number of instructions and is given a unique name. Some assemblers also support passing various parameters to a macro which can be inserted into the code block contained in the macro.

Within a program the assembler replaces all references to the macro's name with the block of code that the macro represents. Essentially macros allow the programmer to give a chunk of code a name and then use it multiple times within a program or even in many programs.

=== C/C++ - Includes ===

The languages C and C++ had a directive named #include which instructs the compiler to insert the contents of a file into the current source file. Typically a program will use this feature to allow certain functions and macros to be used within multiple source files or in multiple programs.

Used in this way, the [http://en.wikipedia.org/wiki/Function_prototype prototype] for a function would be placed in a file and the file that includes the source code to the function and any file that contains source code using the function will use #include to reference the file containing the function prototype. This allows the compiler to reference the source code to the function wherever it happens to be called.

=== Ruby - Mixins and Modules ===

Ruby has several different features that can be used individually or together to allow a programmer to reuse sections of code. One such feature is known as a module. A module contains a block of code and places it underneath a defined name (or namespace). Variables, classes, and functions within a module can be used by referencing the module name followed by a . and then the name of the item in the module.

For instance, if there is a module named Square which contains a function called draw it can be called by writing:

Square.draw()

If a module is referenced within a class definition that module is often referred to as a mixin. Any functions or variables that are defined in the module can be used within the class just as if it was defined directly within the class. For instance a module may define methods that are used in several different classes. Each class that needs one of the methods in the module can include the module as a mixin.

A module can be referenced in a class or program by using either the load or require statements. If the load statement is used the module will be coped into the location of the statement much like an Assembly language macro or a C or C++ include.

If the require statement is used then only one copy of the module is loaded into memory. If the module is changed during runtime all parts of the program using that module see the change immediately since they are all using the same chunk of code in memory.

Because of this property modules in Ruby can act like a direct inclusion or a collection of classes.

== Collections of Classes ==
In some object oriented languages code can be reused by grouping certain classes together under a single name. These collections are known by different names in different languages but they all typically provide a way to reference a particular class within a collection even if a class with the same name may be found in a different collection.

=== Java - Packages ===

Java allows [http://en.wikipedia.org/wiki/Class_(computer_science) classes] to be grouped into a collection known as a package. A program can then reference the package and use the classes defined within it or reference a particular class in a package.

Each package is given a unique name and each class in a package can be referenced by giving the name of the package followed by the name of the class like this:

java.util.Date somedate = new java.util.Date();

=== .NET - Components and Namespaces ===

Microsoft's .NET family of languages allows a class or a group of classes to be compiled into a component. Components typically need to be compiled into a binary [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] containing [http://en.wikipedia.org/wiki/Common_Language_Runtime CLR] code.

Programs can use a component by adding a reference the DLL containing the component's code . Classes contained within a component can then be used just as if the classes were defined directly in the program.

The .NET languages also support a feature called [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespaces] which allows classes to be referenced by a fully qualified name much like Ruby's modules or Java packages. For more complicated designs, a namespace can be nested within another namespace like this:

namespace Shape
{
namespace TwoDimensional
{
public class Square
{
}

public class Circle
{
}
}

namespace ThreeDimensional
{
public class Cube
{
}
}
}

In this case the class Circle could be referenced from another program by placing the Shape namespace into a component and calling:

Shape.TwoDimensional.Circle myCircle = new Shape.TwoDimensional.Circle();

== Comparison ==

Languages that use a form of direct inclusion often make it very easy to reuse any particular block of code in multiple applications or even within the same application. The principal is a very simple one and is usually quite easy to implement in any given language. However, most forms of direct inclusion do not provide a way to avoid conflicts when multiple variables, functions, routines, classes, or methods share the same name.

Languages that group classes into self-contained collections provide a fairly elegant way to avoid name collisions because each class can be referenced using a fully qualified name that includes the name of the collection it is in. They may not be quite as simple or as easy to use as most forms of direct inclusion but the ability to avoid namespace collisions is often worth it. It is also often easier to determine which collection/package/component a class belongs to than it is to determine which included file contains the class in a direct inclusion system which can aid in debugging and troubleshooting problems.

== References ==
* [http://en.wikipedia.org/wiki/Assembly_language#Macros Assembly language]

* [http://en.wikipedia.org/wiki/Header_file Header file]
* [http://msdn.microsoft.com/en-us/library/36k2cdd4(VS.80).aspx The #include Directive]

* [http://www.rubycentral.com/pickaxe/tut_modules.html Programming Ruby Modules and Mixins]

* [http://en.wikipedia.org/wiki/Java_package Java package]

* [http://msdn.microsoft.com/en-us/library/ms973807.aspx Creating Components in .NET]
* [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespace (C# Reference)]

CSC/ECE 517 Fall 2009/wiki2 7 ov

2009-10-07T13:29:53Z

Veovis:

'''Survey of Language Features for Code Reuse'''

== Direct inclusion ==
Code can be reused by simply storing it in a defined location and allowing a compiler or preprocessor to insert a copy of the code whenever it is referenced. This is the simplest form of code reuse and is present in many languages.

=== Assembly Language - Macros ===

Many assemblers have support for macros. A macro is a block of code that can be called from any location in the program. A macro can contain any number of instructions and is given a unique name. Some assemblers also support passing various parameters to a macro which can be inserted into the code block contained in the macro.

Within a program the assembler replaces all references to the macro's name with the block of code that the macro represents. Essentially macros allow the programmer to give a chunk of code a name and then use it multiple times within a program or even in many programs.

=== C/C++ - Includes ===

The languages C and C++ had a directive named #include which instructs the compiler to insert the contents of a file into the current source file. Typically a program will use this feature to allow certain functions and macros to be used within multiple source files or in multiple programs.

Used in this way, the [http://en.wikipedia.org/wiki/Function_prototype prototype] for a function would be placed in a file and the file that includes the source code to the function and any file that contains source code using the function will use #include to reference the file containing the function prototype. This allows the compiler to reference the source code to the function wherever it happens to be called.

=== Ruby - Mixins and Modules ===

Ruby has several different features that can be used individually or together to allow a programmer to reuse sections of code. One such feature is known as a module. A module contains a block of code and places it underneath a defined name (or namespace). Variables, classes, and functions within a module can be used by referencing the module name followed by a . and then the name of the item in the module.

For instance, if there is a module named Square which contains a function called draw it can be called by writing:

Square.draw()

If a module is referenced within a class definition that module is often referred to as a mixin. Any functions or variables that are defined in the module can be used within the class just as if it was defined directly within the class. For instance a module may define methods that are used in several different classes. Each class that needs one of the methods in the module can include the module as a mixin.

A module can be referenced in a class or program by using either the load or require statements. If the load statement is used the module will be coped into the location of the statement much like an Assembly language macro or a C or C++ include.

If the require statement is used then only one copy of the module is loaded into memory. If the module is changed during runtime all parts of the program using that module see the change immediately since they are all using the same chunk of code in memory.

Because of this property modules in Ruby can act like a direct inclusion or a collection of classes.

== Collections of Classes ==
In some object oriented languages code can be reused by grouping certain classes together under a single name. These collections are known by different names in different languages but they all typically provide a way to reference a particular class within a collection even if a class with the same name may be found in a different collection.

=== Java - Packages ===

Java allows [http://en.wikipedia.org/wiki/Class_(computer_science) classes] to be grouped into a collection known as a package. A program can then reference the package and use the classes defined within it or reference a particular class in a package.

Each package is given a unique name and each class in a package can be referenced by giving the name of the package followed by the name of the class like this:

java.util.Date somedate = new java.util.Date();

=== .NET - Components and Namespaces ===

Microsoft's .NET family of languages allows a class or a group of classes to be compiled into a component. Components typically need to be compiled into a binary [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] containing [http://en.wikipedia.org/wiki/Common_Language_Runtime CLR] code.

Programs can use a component by adding a reference the DLL containing the component's code . Classes contained within a component can then be used just as if the classes were defined directly in the program.

The .NET languages also support a feature called [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespaces] which allows classes to be referenced by a fully qualified name much like Ruby's modules or Java packages. For more complicated designs, a namespace can be nested within another namespace like this:

namespace Shape
{
namespace TwoDimensional
{
public class Square
{
}

public class Circle
{
}
}

namespace ThreeDimensional
{
public class Cube
{
}
}
}

In this case the class Circle could be referenced from another program by placing the Shape namespace into a component and calling:

Shape.TwoDimensional.Circle myCircle = new Shape.TwoDimensional.Circle();

== Comparison ==

Languages that use a form of direct inclusion often make it very easy to reuse any particular block of code in multiple applications or even within the same application. The principal is a very simple one and is usually quite easy to implement in any given language. However, most forms of direct inclusion do not provide a way to avoid conflicts when multiple variables, functions, routines, classes, or methods share the same name.

Languages that group classes into self-contained collections provide a fairly elegant way to avoid name collisions because each class can be referenced using a fully qualified name that includes the name of the collection it is in. They may not be quite as simple or as easy to use as most forms of direct inclusion but the ability to avoid namespace collisions is often worth it. It is also often easier to determine which collection/package/component a class belongs to than it is to determine which included file contains the class in a direct inclusion system which can aid in debugging and troubleshooting problems.

== References ==
* [http://en.wikipedia.org/wiki/Assembly_language#Macros Assembly language]

* [http://en.wikipedia.org/wiki/Header_file Header file]
* [http://msdn.microsoft.com/en-us/library/36k2cdd4(VS.80).aspx The #include Directive]

* [http://www.rubycentral.com/pickaxe/tut_modules.html Programming Ruby Modules and Mixins]

* [http://en.wikipedia.org/wiki/Java_package Java package]

* [http://msdn.microsoft.com/en-us/library/ms973807.aspx Creating Components in .NET]
* [http://msdn.microsoft.com/en-us/library/z2kcy19k(VS.80).aspx namespace (C# Reference)]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T17:15:45Z

Veovis: /* Centralized Version Control */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems like [http://www.nongnu.org/cvs/ CVS] and [http://subversion.tigris.org/ Subversion] have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository; so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system, the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may simply require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining some of the advantages of a distributed system such as being able to work while disconnected from the repository; and being able to preserve change history even when a large group of changes is checked in all at once to a central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access certain areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project.

Some may see distributed version control systems as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

* [http://www.gnu.org/software/gnu-arch/ GNU arch]
* [http://monotone.ca/ Monotone]
* [http://darcs.net/ Darcs]
* [http://bazaar-vcs.org/ Bazaar]
* [http://mercurial.selenic.com/wiki/ Mercurial]
* [http://git-scm.com/ Git]

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T17:13:35Z

Veovis: /* Common Distributed Version Control Systems */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository; so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system, the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may simply require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining some of the advantages of a distributed system such as being able to work while disconnected from the repository; and being able to preserve change history even when a large group of changes is checked in all at once to a central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access certain areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project.

Some may see distributed version control systems as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

* [http://www.gnu.org/software/gnu-arch/ GNU arch]
* [http://monotone.ca/ Monotone]
* [http://darcs.net/ Darcs]
* [http://bazaar-vcs.org/ Bazaar]
* [http://mercurial.selenic.com/wiki/ Mercurial]
* [http://git-scm.com/ Git]

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T17:09:59Z

Veovis: /* Conclusion */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository; so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system, the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may simply require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining some of the advantages of a distributed system such as being able to work while disconnected from the repository; and being able to preserve change history even when a large group of changes is checked in all at once to a central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access certain areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project.

Some may see distributed version control systems as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T17:03:00Z

Veovis: /* Architectural Awareness */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository; so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system, the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may simply require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:58:47Z

Veovis: /* Conflict Resolution */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository; so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:57:23Z

Veovis: /* No single point of failure */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the server with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, they can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:55:24Z

Veovis: /* No network connectivity required */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection and access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:53:30Z

Veovis: /* Centralized Version Control */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added, the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file, he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository. This records the changes that were made and makes them available to the other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection to access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:51:35Z

Veovis: /* Centralized Version Control */

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to each file since it was first added to the project.

When a new file needs to be added the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository to record the changes and make them available to other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection to access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:48:55Z

Veovis:

'''Strengths and Weaknesses of Distributed Version Control'''

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to the file since it was first added to the project.

When a new file needs to be added the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository to record the changes and make them available to other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection to access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:47:02Z

Veovis:

Strengths and Weaknesses of Distributed Version Control

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to the file since it was first added to the project.

When a new file needs to be added the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository to record the changes and make them available to other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection to access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:45:17Z

Veovis:

= Distributed Version Control =

== Introduction ==

A version control system is a software package that allows developers to record and track how the source code for a project changes over time. Typically each change is recorded in some form of database along with who made the change and perhaps a description of what the change was or why it was made.

Because each change is recorded it is easy to compare the current version of a particular source file with any older version. It is also possible to restore any source file to the state it was at a particular time in the past which can be useful if a change in a particular file breaks part of the project and needs to be undone.

=== Centralized Version Control ===

Traditionally version control systems have relied on each developer having access to a central server that holds the source code repository for the project. The repository contains a complete copy of all of the files in the project along with all of the changes that have been made to the file since it was first added to the project.

When a new file needs to be added the developer connects to the server with the repository and checks in the new file. When a developer wants to make a change to a file he or she is usually expected to connect to the server and retrieve the current version of the file. The developer then makes the changes and checks in the file to the repository to record the changes and make them available to other developers working on the project.

=== Distributed Version Control ===

A new type of version control system called distributed version control has become popular in recent years. Distributed version control systems do not require a central server to maintain the repository for a project. Instead each developer working on the project has his or her own repository located on their workstation.

Any changes a developer makes to a file are tracked in the developer’s own repository. Each change is given a unique identifier. When the developer A wants to share his or her changes with other developers they can either push the changes directly to the other developer’s repository or they can ask the other developers to retrieve the changes directly from developer A’s repository.

== Advantages of Distributed Version Control Systems ==

=== No network connectivity required ===

One of the more obvious advantages of a distributed system is the fact that developers do not need a network connection to access to a central repository while they are working on a project. Since each developer has his or her own repository they can work on changes without any form of connectivity. All changes are committed to the developer’s local repository and can be shared later whenever the developer has a connection to other developers.

=== Changes can be kept private while preserving change history ===

Developers often want to keep their changes private until they are done working on them and are ready to share them. In a traditional centralized version control system this can result in a developer checking in a large number of changes as a single revision rather than doing incremental check ins for each change. This results in much of the change history being completely lost.

In a distributed system the entire change history is stored in the developer’s local repository. When the developer shares his or her changes with other developers they also have access to the history for those files that are involved in the change. This allows the complete change history to be preserved for each file in the project while still giving the developer control over when they share their changes.

=== Project managers do not need to grant permission to developers ===

In a centralized version control system the project managers often have to grant each developer access to the repository before they can begin to make changes. In a distributed system this is not necessary because a new developer only needs a reasonably current copy of the source code of a project to begin to make changes. Once the developer is ready to share his or her changes they can send them to other developers who can then choose to either accept the changes into their own repositories or reject them.

=== No single point of failure ===

In a centralized version control system if the system with the repository fails or becomes unavailable then developers can not check in new changes or retrieve the change history of anything in the project. In a distributed system if a repository goes down everyone can continue to work without any problems because everything is stored in their local repository. If their local repository becomes corrupted or destroyed, then can simply get a new copy of the repository (perhaps from another developer) and continue working.

== Disadvantages of Distributed Version Control Systems ==

=== Security ===

Sometimes it is desirable to be able to prevent certain developers from accessing certain sections of a project, particularly in a commercial development project. In a centralized system this can be accomplished by having the server only allow access to those parts of the project that the project managers have defined for each developer. In a distributed version control system it is very hard to do this because developers can share changes with each other and there is no easy way to determine what sections of a project a developer may have in his or her repository.

=== Conflict Resolution ===

In any version control system there will be the need for conflict resolution. If more than one developer makes changes to a single file in a project at approximately the same time a conflict can occur. Someone must compare the various versions of the file and merge the changes into a single new version before it can be checked in.

In a distributed version control system each developer is working from their own repository so conflicts are somewhat more likely to occur than in a centralized system. Fortunately, most distributed version control systems are capable of automatically resolving the conflict when a change is shared. When a conflict must be resolved manually, the resulting merged changes can then be easily shared with the other developers working on the project.

=== Architectural Awareness ===

Distributed version control systems allow for great flexibility when choosing how changes should be shared. A distributed version control system can be completely decentralized and changes shared in a pear-to-pear fashion or it can resemble a centralized system, or a mixture of the two.

Different developers will have different changes in their repositories and it may be necessary to connect to the repositories of multiple developers to retrieve the latest version of each file. This can make retrieving a current copy of the source files for a project a bit more difficult especially if the files are being collected to make a release build for the project.

However, it is possible to set up a central repository that developers can send their changes to when they are ready to share them. This allows developers to take advantage of being able to work “offline” from the central repository and share changes directly with other developers while still maintaining a central location where changes can be checked in once the developer is happy with them.

Yet another possibility is for project leaders to set up a central repository but only allow project leaders to send changes to it. In this architecture the project leaders receive changes from the developers and choose whether or not to send them on to the central repository.

In a centralized system the developer knows that all changes are checked in to a single repository and the latest files are always in the repository. When using a distributed version control system, developers must be aware of the overall architecture used by the project to ensure they share their changes in the expected way. A developer must learn whether he or she is expected to send changes to a central repository or if they must be sent to someone else for approval. Some projects may not use a central repository at all and may just require each developer to send changes to all of the other developers in the project.

== Conclusion ==

Distributed version control systems are becoming very popular among development teams and I believe the primary reason for this is the fact that a distributed system can be set up to resemble virtually any architecture imaginable. Development teams can even set them up to act much like a centralized system while still retaining the advantages of being able to work while disconnected from the repository and being able to preserve change history even when a large group of changes is checked in all at once to the central repository (as long as the developer checked in each change incrementally to his or her own repository.)

Unless a project needs to have tight control over which developers can access which areas of the project there is little reason for a development team to use a centralized version control system instead of a distributed version control system. However, cooperation between developers is essential for any project. Some may see a distributed version control system as encouraging developers to work alone with little contact with other team members and only share their changes when they are finished. This can cause problems if the other team members disagree with the changes or how they were implemented. Proper planning and communication can go a long way to prevent this from happening in a project.

== Common Distributed Version Control Systems ==

== References ==

* [http://portal.acm.org.www.lib.ncsu.edu:2048/citation.cfm?id=1572211 Why Are Software Projects Moving From Centralized to Decentralized Version Control Systems?]

* [http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/ Intro to Distributed Version Control]

* [http://blog.red-bean.com/sussman/?p=20 The Risks of Distributed Version Control]

* [http://blog.ianbicking.org/distributed-vs-centralized-scm.html Distributed vs. Centralized Version Control]

* [http://arstechnica.com/staff/cohortes-vigilum/2009/03/distributed-version-control-to-the-rescue.ars Distributed version control to the rescue!]

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:44:01Z

Veovis:

= Distributed Version Control =

Distributed version control is taking root in industry, as an alternative to client-server version control (e.g., CVS, Subversion). Explore the reasons for this, and analyze the strengths of distributed version-control systems such as Mercurial, Git, and Bazaar.

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T15:43:47Z

Veovis:

= Distributed Version Control =
----

Distributed version control is taking root in industry, as an alternative to client-server version control (e.g., CVS, Subversion). Explore the reasons for this, and analyze the strengths of distributed version-control systems such as Mercurial, Git, and Bazaar.

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T12:34:50Z

Veovis:

Distributed Version Control
----

Distributed version control is taking root in industry, as an alternative to client-server version control (e.g., CVS, Subversion). Explore the reasons for this, and analyze the strengths of distributed version-control systems such as Mercurial, Git, and Bazaar.

[[User:Veovis|Veovis]]

CSC/ECE 517 Fall 2009/wiki1a 3 ve

2009-09-04T12:34:41Z

Veovis: