<!--
title: Document with precision
domain: ml-systems
topic: Documentation
language: Dockerfile
source: kubeflow/kubeflow
updated: 2024-08-17
url: https://awesomereviewers.com/reviewers/kubeflow-document-with-precision/
-->

Write informative, consistent, and precise code comments throughout your codebase. When documenting code:

1. **Be specific with references** - When referencing external repositories or sources, link to specific versions and files, not just directories. Use precise language to describe the relationship between your code and external sources.

```
# AVOID:
# Content below is extracted from scripts/Dockerfiles here:
# https://github.com/HabanaAI/Setup_and_Install/tree/main/dockerfiles/base

# BETTER:
# Content below is based on:
# https://github.com/HabanaAI/Setup_and_Install/blob/1.17.0/dockerfiles/base/Dockerfile.ubuntu22.04
```

2. **Add explanatory comments** - Include brief descriptions for significant code blocks, especially when installing components or defining important configurations.

```
# AVOID:
RUN python3 -m pip install habana_media_loader=="${VERSION}"."${REVISION}"

# BETTER:
# Install Habana media loader library for PyTorch integration
RUN python3 -m pip install habana_media_loader=="${VERSION}"."${REVISION}"
```

3. **Maintain consistent styles** - Use consistent comment headers and styles across similar files to improve readability and maintainability.

```
# AVOID mixing styles:
# version details
# and elsewhere:
# args - software versions

# BETTER: Use consistent headers:
# args - software versions
```

Well-documented code improves comprehension, facilitates maintenance, and enhances collaboration among team members.