"Software Parts" Database

Question

I manage a small team of .net developers in what is chiefly a mainframe shop. My boss is trying to integrate my team more closely with the other development teams. One issue that has come up is that the mainframe programmers have what they call a "parts" database. This is a simple database in which you enter a software part (object, unit,report, function, etc.) and the system issues you a part number which becomes the file name of the executable. The system has two purposes; it issues you a part number/name, which has intelligence built in to it to tell you what team it is maintained by and what program subsystem it belongs to, etc. The mainframe has a flat name space so they use these names to avoid using a module name that already exists. Secondly, and you can also enter some comments about the part. Supposedly this can be used to tell others how to use the "part" in question, if it relies on other external technologies, etc., though, when I asked to see useful examples of this, they could not show me any.

Since we don't have a flat name space in .net, I am resisting the proposition of having my team's objects named in a format of AAAA9999. In discussing this with my manager he wanted to know how we track such things in the "intel" world. In my experience is that such details are kept either as comments in the code or help files, or doc manuals/files, etc, which we already have to maintain. I am dubious as to the efficacy of having my developers maintain data in a database as well. My boss says that he wants to be able to ask me such things when he needs to. In actuality he has asked me something like this once in three years. I told him for that amount of traffic, having my developers maintain a database wasn't worth it. It would be better just to consult with the team and/or search the source code when the query came in.

So my question is: Is a database that documents the internal technical details of the different software entities that exist in an organization (in addition to doc manuals, online help, etc.) useful and practical? Has anyone ever used such a thing in their work?

Answer 1

Namespaces, Libraries, Documentation.. In a non-mainframe world, verbose or at least descriptive names in concisely named namespaces possibly split up into logical libraries are almost self-documenting as to use, nature and developer. Of course actual documentation supplementing the programs & libraries is always a good thing.

I don't think it would be advantageous for you to adopt the part/number convention but then again I don't know all the internals of your business.

Answer 2

An architectural overview is critical to success.

In mainframe world, where things are kept flat for historical reasons, folks invent ways to cope and the XXXyyy naming conventions are ubiquitous.

In the mainframe world, the technology choices are limited. At this point, they're largely fixed. The pace of change is glacial. So a stable database to list the descriptions of a stable list of technology elements makes sense.

[Also, since almost everything is a 'program', discussing software components that aren't programs is hard. Worse still, if you have an architecture where you can build a composite application from other applications, the mainframe folks get very confused. This is normal for Python, and relatively easy for Java.]

In non-mainframe world, where things are hierarchical for historical reasons, folks invent ways to cope.

In the Windows world, where technology changes happen in fairly haphazard ways, you need a different coping mechanism. [In the open source world, it's even worse.]

Best practice is to provide a sensible, usable, architectural overview that puts each source code component into some "big picture" context. You are obligated to provide this (in writing). If you win the lottery and walk away tomorrow, what becomes of your .Net architecture? Management (and your replacement) do not want to cope with that. They want something stable and written.

Database, maybe not.

Stable and written, yes.

In Python world, we use Sphinx (with .. automodule) to create documentation from the source.

In Java world, we use JavaDoc to create documentation from the source.

Your best approach is to create a JavaDoc (or Sphinx-like) master document from the source. I'm sure there are appropriate .Net tools for this. If not, read up on JavaDoc, decorate your comment blocks with a Very Simple markup langauge, and cull your own documentation from your own source.

Answer 3

I cannot see the value of such an approach since the environment will support this information directly. For instance, in C# you can use xml comments to generate documentation for all your source code which will then be in an easy to search format. The information that you seek about the code is in that documentation.

You are right that maintaining a separate database does not add value.

Answer 4

Are you subject to auditor inspections? If so, then the database would be handy each time auditors come through. In that case the "database" can just as easily be a Wiki with a brief entry on each application. That can also prove helpful when someone new needs to maintain the software, especially if a bug occurs and you're not sure which app caused the problem (hopefully you have good enough logging that this won't occur though :-) ).