Documentation and Knowledge Transfer

[zippy]

At the very least process flows should be documented. We put a lot of comments in our code as well. We have a trace system which servers to document the code execution as well. it is turned off by default so that it doesn't impact production. Can be easily turned on in dev, test and mirror environments.

If you disciplined about coding standards then this helps as well. Use proper descriptive variable names. Database table names and column names should not be cryptic. Proper coding conventions can go a long way in making the system self documenting.

In database design for example when you create 2 tables that have a foreign key relationship, have column names reflect this. If you have an employee table and a employees_department table then name the linking employee I'd column in both as EMPLOYEE_ID. This makes the relationship intuitive and obvious. The column name is also descriptive. I have seen tables with column names ESF08A. You have to waste time tracking down what this means.

 

[semaphore]

All our processes are designed in our internal workflow system we wrote, you are able to export all processes to UML or other formats to view.

 

[_kabal_]

Yeah it is documentation you're right. But how do you structure and maintain it? Is it just not that important in your context or do you have a methodology to preserve it? It sounds like there could be some serious pitfalls with that approach.

Not sure how your concerns around maintenance is any different to "normal" documentation.

The world has successfully used javadoc style documentation decades, he is not doing something unique.

 

[_kabal_]

In database design for example when you create 2 tables that have a foreign key relationship, have column names reflect this. If you have an employee table and a employees_department table then name the linking employee I'd column in both as EMPLOYEE_ID. This makes the relationship intuitive and obvious. The column name is also descriptive. I have seen tables with column names ESF08A. You have to waste time tracking down what this means.

You don't really call your PK on your employee table EMPLOYEE_ID? Do you call the first name field EMPLOYEE_FIRST_NAME? I must be incorrectly reading what you said.

 

[cguy]

I don't comment every time little method unless its kinda obtuse. i.e. PerformEuclideanRotation

It's only obtuse if it special cases angles greater than 90 degrees and less than 180. ;-)

 

[semaphore]

It's only obtuse if it special cases angles greater than 90 degrees and less than 180. ;-)

I know

 

[zippy]

You don't really call your PK on your employee table EMPLOYEE_ID? Do you call the first name field EMPLOYEE_FIRST_NAME? I must be incorrectly reading what you said.

Doesn't really matter. I have seen this. If you have an id column for another purpose then you should. The key is to be consistent and use the same conventions. Naming the column like this makes your sql statements easier to read as well. Some sql can get quite lengthly and you may have multiple id columns across tables. Yes, they will have table aliases, but it does make things easier and serves the cause of documenting your system.

 

[semaphore]

Doesn't really matter. I have seen this. If you have an id column for another purpose then you should. The key is to be consistent and use the same conventions. Naming the column like this makes your sql statements easier to read as well. Some sql can get quite lengthly and you may have multiple id columns across tables. Yes, they will have table aliases, but it does make things easier and serves the cause of documenting your system.

Please move into 2014. That is just shoddy crap naming conventions. _ really? Gawd.

 

[Sonic2k]

At the very least process flows should be documented. We put a lot of comments in our code as well. We have a trace system which servers to document the code execution as well. it is turned off by default so that it doesn't impact production. Can be easily turned on in dev, test and mirror environments.

If you disciplined about coding standards then this helps as well. Use proper descriptive variable names. Database table names and column names should not be cryptic. Proper coding conventions can go a long way in making the system self documenting.

In database design for example when you create 2 tables that have a foreign key relationship, have column names reflect this. If you have an employee table and a employees_department table then name the linking employee I'd column in both as EMPLOYEE_ID. This makes the relationship intuitive and obvious. The column name is also descriptive. I have seen tables with column names ESF08A. You have to waste time tracking down what this means.

Worked for a company not long ago.. I was told that putting comments in code is costing the company money i.e. wasting time on the job.

 

[zippy]

Worked for a company not long ago.. I was told that putting comments in code is costing the company money i.e. wasting time on the job.

You get that. It's the type of company you want to leave as soon as possible. They tend to get away with it for a while and it looks like things are improving. But over time the system becomes impossible to maintain and you find the number of post-release bugs starts to increase significantly.

 

[semaphore]

You get that. It's the type of company you want to leave as soon as possible. They tend to get away with it for a while and it looks like things are improving. But over time the system becomes impossible to maintain and you find the number of post-release bugs starts to increase significantly.

Then a company should implement mocking and unit testing.