登录查看更多内容

How can you best organize your OR code documentation?

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

Operations research (OR) is a discipline that applies mathematical and analytical methods to solve complex problems and optimize decisions. OR code documentation is the process of creating and maintaining clear, concise, and consistent information about your OR code, such as its purpose, structure, inputs, outputs, assumptions, and limitations. OR code documentation can help you and others understand, reuse, modify, and debug your code, as well as communicate your findings and recommendations. In this article, we will discuss how you can best organize your OR code documentation using some general principles and best practices.

此文章中的业界达人

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

1 Define your scope and audience

Before you start writing your OR code documentation, you should define the scope and audience of your project. The scope refers to the problem you are trying to solve, the objectives you are trying to achieve, and the methods you are using. The audience refers to the people who will read, use, or review your code documentation, such as yourself, your colleagues, your clients, or your reviewers. Depending on your scope and audience, you may need to adjust the level of detail, the format, the style, and the tone of your code documentation. For example, if your code is for internal use only, you may use more technical terms and abbreviations, but if your code is for external use, you may need to explain them more clearly and avoid jargon.

添加您的观点

Marcus Nascimento

Course Coordinator @ Fatec S?o José dos Campos | PhD candidate in Air Transportation
举报内容
I’m having a good experience in using GitHub to document my OR solutions. GitHub became a good community that aggregates more than just code.

已翻译

赞
Anand Abhishek

AI/ML/Data science/Operations research Leader @ koch Business solutions pvt ltd
举报内容
Having tried different approaches I can say definitely OOPs are the most effective way to go about OR problems Structuring each constraint , objective and other sections separately along with their mathematical definition not only helps in documentation but it helps you debugging and also the most powerful thing is when you want to relax and nullify some constraint it’s easier. This also helps you deploy solutions at scale and hands off with engineers are much easier than any other options

已翻译

赞

2 Follow a consistent structure and format

A good way to organize your OR code documentation is to follow a consistent structure and format throughout your project. This can help you and others navigate, search, and access your code documentation more easily and efficiently. A common structure for OR code documentation is to have a main document that summarizes your project and links to other documents that provide more details on specific aspects of your code, such as data sources, data processing, models, algorithms, results, and analysis. A common format for OR code documentation is to use a standard markup language, such as Markdown, HTML, or LaTeX, that allows you to create readable and attractive documents with headings, lists, tables, figures, equations, and code blocks.

添加您的观点

Shiv Joshi

Clinico-Social Doctor | Researcher | Ethical and Compassionate Leadership | MD Community Medicine
举报内容
Organizing my operations research (OR) code documentation is crucial for clarity and collaboration. It's not about haphazardly jotting down notes; it's a systematic approach. I start with a clear structure, including a well-defined naming convention and file hierarchy. I use comments liberally to explain code logic, functions, and variable meanings. I document my assumptions, data sources, and any external libraries used. I maintain version control, so changes are tracked. I regularly update and review my documentation to ensure it remains accurate and relevant. In OR, organized code documentation is the compass that guides understanding, fosters collaboration, and ensures my code's long-term viability.

已翻译

赞
Ashraf El Gaaly

PhD, Industrial Engineering. Operations Research & Data Science. Mathematical and Statistical modeling. Supply Chain & Logistics
举报内容
I usually structure my code in three main blocks. First, the pre modeling block where I process the data. I try my best to make it as general as I can, so even if my data format changes, I don’t have to overhaul that whole block. Second, building the model. I try to state the general constraint first, like flow conservation in a network problem. Then any specific ones for my problem. Also give your variables and constraints descriptions. Finally, post processing where I analyze the results. Here those descriptions of variables and constraints become handy

已翻译

赞

3 Use clear and concise language

Another important aspect of organizing your OR code documentation is to use clear and concise language that conveys your message effectively and avoids ambiguity and confusion. You should use simple and direct sentences, avoid unnecessary words, use active voice, use consistent terminology, and define any acronyms or technical terms. You should also use proper grammar, spelling, and punctuation, and proofread your code documentation before publishing or sharing it. Additionally, you should use comments in your code to explain the logic, function, and purpose of each block of code, as well as any assumptions, parameters, or limitations.

添加您的观点

Himadri Sen Gupta

PhD Candidate @ University of Oklahoma | Industrial & Systems Engineering
举报内容
I make sure my OR code is easy to understand and use. I use clear names for things in my code, so others can follow along. I also add comments and explanations to help people know what each part does. I like to use Jupyter notebooks, which are like interactive documents, to show how things work step by step. This makes it easier for everyone to see and learn from the code. I use a tool called Git to keep track of changes to my code. It's like a history book for my projects. And I share my code on GitHub, which is like a library for code. In each project, I create a README file that explains what the code does, how to use it, and more. This way, people can use my code and even work together on it.

已翻译

赞

4 Include relevant and accurate information

One of the main goals of your OR code documentation is to provide relevant and accurate information that supports your problem-solving process and decision-making recommendations. You should include information that describes the problem you are solving, the objectives you are pursuing, the data you are using, the models you are building, the algorithms you are implementing, the results you are obtaining, and the analysis you are performing. You should also include information that validates your data, models, algorithms, results, and analysis, such as sources, references, citations, tests, checks, errors, uncertainties, and assumptions. Moreover, you should include information that explains your choices, trade-offs, limitations, and implications of your code, such as rationale, criteria, alternatives, sensitivity, robustness, and recommendations.

添加您的观点

5 Update and maintain your code documentation

Finally, you should update and maintain your OR code documentation as your project evolves and changes. You should keep track of the changes you make to your code, data, models, algorithms, results, and analysis, and reflect them in your code documentation. You should also review your code documentation periodically and make sure it is still relevant, accurate, and consistent. You should also solicit feedback from your audience and incorporate any suggestions or corrections that can improve your code documentation. By updating and maintaining your code documentation, you can ensure that it reflects the current state and quality of your project and that it remains useful and reliable for yourself and others.

添加您的观点

6 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?

添加您的观点

Steven Stark

Top Operations Research (OR) Voice on LinkedIn | Over 20k followers | Follow for OR, Python, Interviewing Content and More | All Opinions are my own
举报内容
Jupyter Notebooks can be a great way to document models because you can use Markdown to write formulas, provide descriptions, etc., in cells and then write the corresponding Python code in the cell beneath it.

已翻译

赞
Yvonne Smeenge

Senior Analyst CoolblueDelivers at Coolblue | Data Analytics, Data Science & Operations Research
举报内容
To this article you can add a paragraph on where to save you code. For instance, I would recommend GitHub. It allows you to create, store, change, merge and collaborate on code and files. You can give access to team member to make changes as well and everyone can see the most recent version in real-time.

已翻译

赞

Operations Research

+ 关注

给文章评分

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

很棒不太好

举报此文章

查看全部

How can you best organize your OR code documentation?

1

2

3

4

5

6

1 Define your scope and audience

2 Follow a consistent structure and format

3 Use clear and concise language

4 Include relevant and accurate information

5 Update and maintain your code documentation

6 Here’s what else to consider

Operations Research

给文章评分

感谢您的反馈

更多Operations Research相关文章

更多相关阅读内容

How can you best organize your OR code documentation?

1

2

3

4

5

6

1 Define your scope and audience

2 Follow a consistent structure and format

3 Use clear and concise language

4 Include relevant and accurate information

5 Update and maintain your code documentation

6 Here’s what else to consider

Operations Research

给文章评分

感谢您的反馈

查看其他技能