Add clarifying comments to improve code readability and maintainability when code behavior isn't immediately obvious. Two key practices to follow: 1. **Label non-obvious function arguments** with the `/*arg=*/` prefix to clarify their purpose. This is especially important for boolean flags, magic numbers, or default values where the meaning isn't...
Add clarifying comments to improve code readability and maintainability when code behavior isn’t immediately obvious. Two key practices to follow:
/*arg=*/ prefix to clarify their purpose. This is especially important for boolean flags, magic numbers, or default values where the meaning isn’t self-evident.Example:
// Poor: Parameters without context
rescaled_type = uint8_type.clone(buildQTypeFromMinMax(
builder, uint8_element_quant_type.getExpressedType(),
builder.getF64FloatAttr(type_range_min),
builder.getF64FloatAttr(type_range_max),
builder.getI32IntegerAttr(
uint8_element_quant_type.getStorageTypeIntegralWidth()),
0, true, builder.getBoolAttr(narrow_range)));
// Better: Non-obvious arguments labeled
rescaled_type = uint8_type.clone(buildQTypeFromMinMax(
builder, uint8_element_quant_type.getExpressedType(),
builder.getF64FloatAttr(type_range_min),
builder.getF64FloatAttr(type_range_max),
builder.getI32IntegerAttr(
uint8_element_quant_type.getStorageTypeIntegralWidth()),
/*bias=*/0, /*signed=*/true, builder.getBoolAttr(narrow_range)));
For instance, when writing code that manipulates compiler include paths:
// This fixes include paths by also including paths where resolved symlinks are replaced
// by the original paths. Example:
// If cc returns "/usr/bin/gcc/lib/include" but the actual path is a symlink from
// "/usr/lib/include", both paths will be included to ensure proper header resolution.
These documentation practices help other developers understand code intent without having to reverse-engineer the logic, reducing maintenance burden and preventing bugs during future modifications.
Enter the URL of a public GitHub repository