Tag Archive: best practices

Software Engineering vs Other Engineering Disciplines

Here’s a great presentation by Glenn Vanderburg describing the similarities and differences between software engineering and other engineering disciplines.  He notes that is not unusual that software is different from other engineering because all other engineering disciplines are in fact also different from each other.  He emphasizes the importance of testing because as in other engineering disciplines mathematical modeling is not proof, it is only used as a form of cost reduction.  Only empirical testing is “proof”.

Some assumptions about software engineering that were once true, but are no longer true:

  • Code is hard to read
  • Code is hard to change
  • Testing is expensive

Some assumptions that were once believed to be true, but were never true:

  • All engineering is like structural engineering
  • Programming is like building
  • Modeling and analysis are about correctness

It is well worth the 51 minutes, enjoy!

Documentation best practices

Here are some thoughts about documentation, including guidelines and best practices on documentation of code, defects, and application usage.

Code Documentation

I’ve worked in a lot of different development teams at a lot of different companies and I can say that no one even tries to create hard rules around documentation of code for developers.  Mostly it’s because it’s so subjective, but also because it would be so hard to enforce.  However, a general guideline or “best practices” for code documentation would include:

1)  Use meaningful variable and property names (i.e. call a variable “agency”, not “a”;  call a property “DependentService” instead of “ds”, etc.)

2)  Use meaningful method or function names instead of code comments.

For example:

public void GetDependentServiceForXYZService()

instead of

// get dependent service for XYZ service
public void GetService()

3)  Don’t add pointless, redundant, or obvious code comments.

Example 1:  Don’t do this:

// get dependent service for XYZ service
public void GetDependentServiceForXYZService()

Example 2:  Don’t do this either:

// set agency to null
agency = null;

3) In general, only add code comments for anything that’s may seem out of the ordinary or that you yourself as the developer may cause you to get confused when you look at your own code 6 months from now.

Defect Documentation

Documentation for requirements and defects found in QA testing will need to be much more strictly enforced because there are certain things everyone (developers, testers, acceptance managers, etc) need to know to replicate, fix, and retest the issue.  Things that would need to be known for documenting a defect include:

1)  What screen was the error seen?

2)  Steps for reproducing the error

3)  What environment was the bug found?  (i.e. dev, qa, pre-prod, acceptance, production, etc)

4)  Date it was found

5)  Version of the code it was found in

6)  Who the bug is assigned to for fixing, who should it be assigned to for re-testing, etc.

7)  Screenshots of the error would be nice

All of these can be easily enforced with a bug tracking tool like Remedy, TFS, etc.

User Documentation

Documentation for using the application is a different ball game.  There are definitely no rules here, every company and every app had different requirements for user manuals.  Usually acceptance managers/testers, business analysts, and QA testers are (a lot) better than developers at documenting how the app is actually used by the business.  Usually help links/popups are best for documenting an app because no one reads the manual.  If you have a really complex app, you may need to hire a tech writer/trainer to document everything for you.  Short videos of how to use features or complete tasks with the app are awesome (they’re also much appreciated when learning linear algebra www.khanacademy.org).

Separation of Concerns Principle

Fear of making changes to your system or difficulty in following code logic are signs that your legacy code has consistently violated the Separation of Concerns principle. The Separation of Concerns principle is a cornerstone of good engineering and a hallmark of using this principle is code that’s easy to read, easy to test, and easy to refactor. The Separation of Concerns principle is about creating stable, easily maintainable code, systems that won’t fall to pieces just because you made one little change (or even sweeping changes) somewhere. Code that is separated by layers is easier to automatically test, and automated tests make code even easier to refactor. Code that is effectively organized also allows more developers to work on a project without tripping over each other in source control, either by waiting to check out a file or puzzling through a change-comparison.

View full article »

© 2017 Robert Corvus