Code Quality Assurance and Classification

[Stefan Ram]

I will describe a problem and my solution. I wonder how others
are doing this.

Problem:

One wants to publish source code, but does not know whether
the source code might contain confidential parts.

Solution:

One does a code review, and if the code is not found to
contain confidential parts, it gets a "clearance stamp":

@de.dclj.ram.meta.description.Cleared()
public interface ComparableLocatableTuple { ... }

Problem:

After the clearance was granted, the code might be edited and
the edit session might introduce confidential notes into the
code, again. The clearance stamp then will be misleading.

Solution:

The clearance stamp gets a date and time:

@de.dclj.ram.meta.description.Cleared("slr@2006-01-31T19:14:50+01:00")
public interface ComparableLocatableTuple { ... }

Now the publishing process will compare the time of the last
modification of the file with the clearance stamp. If the
last modification occured later than the clearance (plus
a tolerance of some seconds), the clearance will be considered
invalid. Files with invalid clearances will need a new
review to be possibly re-granted clearance.

Extended Solution:

The review might annotate the type by code qualities such as
documentation:

@de.dclj.ram.meta.description.Cleared("slr@2006-01-31T19:14:50+01:00")
@de.dclj.ram.meta.quality.Documented()
public interface ComparableLocatableTuple { ... }

This means that the type declaration was sufficiently
documented at the time of the review.

Using this annotation, code which is not sufficiently
documented can be found more easily in the source tree as a
candidate for documentation sessions.

If the file is modifid (code is added or modified) not only
will the clearance become invalid but also the "Documented"
stamp. (When one is in a hurry to extend features or remove a
bug, one does not always take time and care to update the
documentation immediatly.) So, the next code review also would
have to decide whether the type declaration still is
considered sufficiently documented.

If not, the "Documented" stamp will be removed and the
declaration then again is a candidate for a documentation
session.

In a similar manner other code qualities might be handled,
such as "Tested".

This whole effort will allow to:

- make sure that only code is published that has
a certain number of qualities (such as non-
confidential or documented)

- easily find those type declarations that lack certain
qualities as candidates for edit sessions to
improve them.

 

[Joe Attardi]

One does a code review, and if the code is not found to
contain confidential parts, it gets a "clearance stamp":

@de.dclj.ram.meta.description.Cleared()
public interface ComparableLocatableTuple { ... } ....

@de.dclj.ram.meta.description.Cleared("slr@2006-01-31T19:14:50+01:00")
public interface ComparableLocatableTuple { ... }

My initial impression is, "wow that's overly complicated!" But it
sounds like this was a real problem at your organization.

So after giving it another thought, I must say, that's pretty cool. The
only downside I see is that source files will get littered with these
@Cleared annotations.

Still, a clever use of annotations!

 

[Thomas Weidenfeller]

After the clearance was granted, the code might be edited and
the edit session might introduce confidential notes into the
code, again. The clearance stamp then will be misleading.

Solution:

The clearance stamp gets a date and time:

@de.dclj.ram.meta.description.Cleared("slr@2006-01-31T19:14:50+01:00")
public interface ComparableLocatableTuple { ... }

How secure needs the solution to be? A time stamp is easy to update by
the programmer, when the code is updated, too.

If you want to have it more tamper-proof consider a digitally signed
checksum, where the reviewers sign with their private keys.

This whole effort will allow to:

- make sure that only code is published that has
a certain number of qualities (such as non-
confidential or documented)

- easily find those type declarations that lack certain
qualities as candidates for edit sessions to
improve them.

And don't forget, it will drive programmers mad. Some managers might
consider this an advantage.

/Thomas

 

[Chris Uppal]

One does a code review, and if the code is not found to
contain confidential parts, it gets a "clearance stamp":

@de.dclj.ram.meta.description.Cleared()
public interface ComparableLocatableTuple { ... }

[... etc ...]

One problem I have with this approach is that you are changing the file /after/
it has been signed-off, so what was approved or certified is not identical to
what is /claimed/ to be approved or certified. That might not matter for some
applications, but for the general case I think I'd prefer to use an approach
(perhaps based on something like digital signatures) where the certificate is
stored separately from the file to which it applies.

BTW, there might also be a need for similar kinds of certifications for .class
or .jar files too.

-- chris

 

[Chris Uppal]

And don't forget, it will drive programmers mad.

A major irritation would be remembering to remove the certification annotations
when copy/pasting code. <wink/>

-- chris