How do you document inherited code?

由人工智能和领英社区提供技术支持

Inheriting code from other developers can be challenging and frustrating, especially if the code is poorly documented or not documented at all. Documentation is essential for understanding, maintaining, and improving code, but it can also be time-consuming and tedious to write. How do you document inherited code without spending too much time or losing your sanity? Here are some tips and best practices to help you document inherited code effectively and efficiently.

此文章中的业界达人

由社区从 13 条内容中精选。了解更多

Ryan Javanshir

DevOps Engineer and Game Developer

1 Assess the current state

Before you start documenting inherited code, you need to assess the current state of the documentation. Is there any existing documentation, such as comments, README files, API docs, or user manuals? If so, how accurate, consistent, and comprehensive is it? Does it follow any standards or conventions? You can use tools like Doxygen, Javadoc, or Sphinx to generate documentation from code comments and annotations, or use linters and style checkers to identify and fix formatting and syntax issues. You can also use code analysis tools like SonarQube, CodeClimate, or NDepend to measure the quality, complexity, and maintainability of the code.

添加您的观点

Ryan Javanshir

DevOps Engineer and Game Developer
举报内容
More recently, it is possible to enter code into tools like ChatGPT and ask it to explain the code to you, either giving you a summary or going through it in great detail. This is one potential starting point if you feel completely lost at the beggining.

已翻译

赞
Damith Bandara

? iOS Mobile Engineer | Senior Software Engineer at Accenture
举报内容
To document inherited code, add comments that explain the purpose, logic, and important details of functions, classes, and complex parts. Use clear and concise language, and create a high-level overview of the code base's architecture and dependencies. Keep documentation updated as the code evolves.

已翻译

赞

加载更多内容

2 Identify the gaps and priorities

Once you have a clear picture of the current state of the documentation, you need to identify the gaps and priorities. What are the most critical or frequently used features, functions, or modules of the code? What are the most confusing or ambiguous parts of the code? What are the most common or potential errors or bugs in the code? What are the dependencies, inputs, outputs, and side effects of the code? You can use tools like Git, GitHub, or Bitbucket to track the history, changes, and issues of the code, or use tools like Codecov, Coveralls, or Codacy to measure the test coverage and code quality of the code.

添加您的观点

Ryan Javanshir

DevOps Engineer and Game Developer
举报内容
When considering which gaps and priorities to work on first, it's a good idea to identify the most valuable changes. If you find the bottlenecks, and the parts of the codebase that could be optimised to give quick wins, you are using your time to extract the most value from your work. For example, if you're reviewing a deployment pipeline, find the areas that are the most time consuming and determine whether this can be improved.

已翻译

赞

加载更多内容

3 Write the essential documentation

After you have identified the gaps and priorities, you need to write the essential documentation. This includes documenting the purpose, functionality, and usage of the code, as well as the assumptions, limitations, and design decisions of the code. You can use tools like Markdown, AsciiDoc, or reStructuredText to write documentation in a simple and readable format, or use tools like MkDocs, Docusaurus, or VuePress to generate static websites from documentation files. You can also use tools like Swagger, Postman, or Insomnia to document and test RESTful APIs, or use tools like Graphviz, PlantUML, or Mermaid to create diagrams and charts from code.

添加您的观点

Ryan Javanshir

DevOps Engineer and Game Developer
举报内容
Keep your documentation concise and to the point. The primary aim should be to allow the next developer, in the least amount of time, to understand the code and make changes when required.

已翻译

赞

加载更多内容

4 Update and maintain the documentation

Finally, you need to update and maintain the documentation as you work on the code. This means documenting any changes, additions, or deletions to the code, as well as any new features, enhancements, or fixes to the code. You can use tools like GitBook, Read the Docs, or Docsify to host and update documentation online, or use tools like Git, GitHub, or Bitbucket to version control and collaborate on documentation files. You can also use tools like Sphinx, Jekyll, or Hugo to integrate documentation with code, or use tools like Travis CI, Jenkins, or GitHub Actions to automate documentation generation and deployment.

Documenting inherited code can be a daunting task, but it can also be a rewarding one. By following these tips and best practices, you can document inherited code more effectively and efficiently, and make your life and your colleagues' lives easier and happier.

添加您的观点

加载更多内容

5 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?

添加您的观点

加载更多内容

Programming

+ 关注

给文章评分

我们借助人工智能创建了此文章。您认为这篇文章怎么样？

很棒不太好

举报此文章

查看全部

How do you document inherited code?

1

2

3

4

5

1 Assess the current state

2 Identify the gaps and priorities

3 Write the essential documentation

4 Update and maintain the documentation

5 Here’s what else to consider

Programming

给文章评分

感谢您的反馈

更多Programming相关文章

更多相关阅读内容

How do you document inherited code?

1

2

3

4

5

1 Assess the current state

2 Identify the gaps and priorities

3 Write the essential documentation

4 Update and maintain the documentation

5 Here’s what else to consider

Programming

给文章评分

感谢您的反馈

查看其他技能