TransWikia.com

Guideline for use of definite and indefinite articles in source code documentation

English Language & Usage Asked on January 25, 2021

I have a doubt about proper use of definite and indefinite articles is source code documentation.

For example:

/**
 * Opens the door.
 *
 * @param speed The opening speed in cm/s.
 * @param alarm The alarm that is turned on while the door is opening.
 * 
 * @returns The promise that is resolved once the door is fully open.
 */
 open(speed: number, alarm: Alarm): Promise<void>;

and

/**
 * Opens the door.
 *
 * @param speed An opening speed in cm/s.
 * @param alarm An alarm that is turned on while the door is opening.
 * 
 * @returns A promise that is resolved once the door is fully open.
 */
 open(speed: number, alarm: Alarm): Promise<void>;

In the second example, the description of ‘speed’ is not right. However, I am not completely sure about the use of the articles in the ‘alarm’ description and in the return description.

Which is better in each case and why? Is there a grammar rule that justifies a decision or a best practice here?

Add your own answers!

Ask a Question

Get help from others!

© 2024 TransWikia.com. All rights reserved. Sites we Love: PCI Database, UKBizDB, Menu Kuliner, Sharing RPP