Describe code

As product requirements evolve, source code does too. It is important to document functions, database schemas, and components by describing their purpose and ensuring these descriptions stay updated. These source code descriptions serve two key purposes: they help product and engineering teams understand the code's intent while also providing crucial context to LLMs for better code comprehension and to enable semantic retrieval.

Examples

UserService (Service/Class)
This service handles user creation, authentication, and profile management.

createUser (Function)
Creates a new user in the system.

RadioGroup (React component)
Presents two or more radio button options within a fieldset, each with a label and descriptive text explaining the choices.

Recommendation

Documentation of source code should be placed in accessible locations that extend beyond the current application's context. This can be achieved through inline documentation, dedicated documentation files, API generators, and centralized knowledge bases. The key is maintaining consistent formats that are both human-readable and machine-parseable, while ensuring source code descriptions remains synchronized with code changes.