Integration

This document was last edited 07/18/2002 10:22:06 PM by Eddie Pettis (npettis@engr.uark.edu)

Most programmers feel constrained by forcing standards and guidelines upon them. As a result, the PARAGON team has opted for a list of preferences on how we would like to see things done. We do not force others to name variables a certain way or put a formal header on the top of each method, but there is a certain understanding that if the code is not descriptive, it will be impossible to maintain. Below are a list of accepted practices that we have adopted.

What's New:

7.18.02: Modified after completing comprehensive code review

3.28.02: Added standard dialog layout

HappyDoc Comment Formatting

To aid in the development process, we have implemented the use of HappyDoc as an automatic documentation tool. Every method should have the proper formatting for proper display in HappyDoc. Basically, we would like to be able to reference all of our methods in a format similar to the Qt documentation site. This allows all users to modify source code easily.

The proper formatting for a method is shown below.

# bar = foo( str, int )

#	Accepts a str and a number int.  Returns a string consisting

#	that is repeated int times.

def foo( self ):

...

	The first character after a hash comment must be a space.
	The line immediately above the definition is plain text.
	The top line before the empty line is boldfaced.
	Any new-line characters must be represented by a blank line between comments.

Code-Level Documentation

Rather than comment the obvious, we choose to write meaningful comments about how a segment of code is supposed to work. This keeps the user from reading excess comments that do not contribute to the readability of the code and retaining those that are important to understanding how the code is supposed to work. Additionally, we attempt to comment any "surprise" lines of code that do not really appear to be practical. All of these features are detailed in the following example.

class parBadExample:

	def counting( self ):

		# initialize x

		x = 0

		# count to 20

		while( x<=20 ):

			# add 1

			x += 1

		# (no comments here)

		if( foo.bar().nextChild and not self.try.and.read.this() ):

			self.performFreakyAction( foo.bar().codec() )

class parGoodExample:

	def search( self, string ):

		# search for specified string in list of connection points

		for connPoint in self.connPoints[:]:

			if( connPoint.name == string ):

				return connPoint

		return None

	def divideByTwo( self, number ):

		# right shift result to reduce processing time

		return (number>>1)

Classes

Since Python is an object-oriented language, we feel that the default method of data storage should be a class. This allows future versions of PARAGON to communicate between interfaces. We are currently in the process of modifying the various interfaces to handle shared data classes, so this particular guideline is extremely important. Please refer to the HappyDoc documentation for information on these shared clsses.

Modularity is Important

We feel that our code should be modular enough to rip various sections out and use them in another program. This is not always feasible between the four main interfaces and the Composer, but we would like to attempt this whenever possible. Examples of this principle include the Code Generator, which use only a formatted dom-tree, and the proposed Equation Parser, which only requires string inputs.

Problems with the site? Need to add information? E-mail the webmaster at npettis@engr.uark.edu.
http://mixedsignal.eleg.uark.edu	Last updated by Eddie Pettis 07.19.2002 12:36:11 PM -0500

What's New:

HappyDoc Comment Formatting

Code-Level Documentation

Classes

Modularity is Important

Problems with the site? Need to add information? E-mail the webmaster at npettis@engr.uark.edu.

http://mixedsignal.eleg.uark.edu

Last updated by Eddie Pettis

07.19.2002 12:36:11 PM -0500