Skip to main content

Documenting and handing over Source Code [Resolved]

I have recently left my previous student job as a part time developer for at small ERP management firm.

During my time at the firm i have developed several modules for integration with the ERP system. Furthermore i have developed an application, and a backend for said application.

I have been asked to document the complex parts of my codebase, so that another developer might be able to take on further development.

Is there any best practice in handing over source code, how should i document, and to what extend should i document?

As a last note i have not been making any tests, or any documentation of the code, other than comments to help navigate the code structure. The product owner simply did not want me to spend time on those activities.

Any input is appreciated !

Question Credit: BastianBuhrkall
Question Reference
Asked April 16, 2019
Posted Under: Programming
2 Answers

There are really three aspects to this question, as I understand it.

You were a part-time developer for a company while you were a student. During the course of the work, the product manager did not want you to spend time on test and documentation.

This, alone, is a huge risk to the success of a product.

Some level of documentation is important for many reasons, from onboarding new team members to helping the existing team members understand what they did in the past and why they did it. The level and detail of the documentation depends on various factors, such as the complexity of the system under design and development, organizational size and structure, compliance requirements, and more.

Neglecting tests, which can also be a form of documentation, has a huge risk to product quality. Writing automated tests not only capture the current intended behavior of the system at various levels of abstraction, but as the design changes, a failing test will raise a flag if a change to the code causes a change in behavior. This will force the developer to think about the change and make sure it's appropriate while, with well-written tests, highlight the scope and impact of the changes.

Since you were a student and not a full-time employee, I don't think you were in a position to push back too hard on this request. However, I would make sure that if documentation is ever neglected, to raise it as a risk for the future and make sure that it's documented and tracked. How that's done varies by team and organization.

At some point, you've left this position and are no longer employed by this organization, but they are asking you to do work.

This situation falls into the realm of navigating the workplace and your career, which is a better fit for The Workplace than Software Engineering. However, I would suggest that you never work for free. As I mentioned earlier, the organization took a risk by deferring documentation. And instead of just deferring it to a reasonable point, they deferred it beyond your employment. I am opposed to working for free, so I would say that you are no longer obligated to support a previous employer and find diplomatic ways to avoid this work, making the organization eat the costs associated with their decisions.

Now, you're looking for good practices going forward with respect to documenting software that you are responsible for building.

I would recommend reading Martin Fowler's writing about UML Modes, especially UML As Notes and UML As Sketch. This doesn't just apply to UML, but any standardized modeling language. The general idea is that just because a formal modeling language gives you a vast set of tools doesn't mean you need to use all of them. You can use the core language correctly to have advantage of recognized and commonly understood symbols, but at various levels of abstraction and detail that are appropriate for your audience.

Next, I'd look at a variety of modeling notations from standard flowchart notation to UML and SysML to the C4 model to IDEF. These are notations that have documentation associated with them. The advantage is that you can find an appropriate type of diagram, call it by name, and perhaps provide a link or reference to how to read it for people who don't know the modeling language. This saves you the time of having to define a language and communicate both a software design, but also the design language used to document the software design. In addition, you aren't limited to graphical notations - text and tables go a long way, too.

Finally, I'd look at the techniques of Agile Modeling. It's a set of principles and techniques to align the creation of software design documentation with the lean and agile values and principles. There are techniques out there to balance creating working software with creating appropriate and useful documentation.

credit: Thomas Owens
Answered April 16, 2019

This is a case for minimal, though professional, effort. Make an automatic listing of all classes/components. A kind of "completeness."

Then make a structured rich-text document bringing everything in context, what is a controller, what an entity class, how they are used together.

Maybe a glossary too.

And at the top tools, architecture.

Menus, screenshots and other things you still can/want to collect.

In this way a future developer can find hishers way in the software.

credit: Joop Eggen
Answered April 16, 2019
Your Answer