Signature
ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize)
Checklist
Doxygen
(bullet points are in order of appearance)
- First line explains briefly what the function does
- Simple example or snippet how to use the function
- Longer description of function containing common use cases
- maxSize special case has very long description (>50% of body)
- maxSize special case move description to pre / post / return values
- mention explicitly, that user has to manage their buffer
- move special case 'not enough space' to return values / pre / post
- Description of functions reads nicely
- remove / define abbreviated (make it more explicit)
- "Writes keyName of `key` into the provided buffer `returnedName` if it is shorter than `maxSize`"
@pre
returnedName
is a pre-allocated buffer
- maxSize is the size of
returnedName
@post
returnedName
contains the name of the Key
@param
for every parameter
returnedName
: pre-allocated buffer to write the key name into
@return
/ @retval
1
: when only a null-terminator was written
-1
: standardize / change 'keyname' / 'key name' or 'Key name'
-1
check if null pointer case is even still applicable
-1
split into two lines: maxSize / NULL pointer
Naming
- Abbreviations used in function names must be defined in the Glossary
- Function names should neither be too long, nor too short
- Function name should be clear and unambiguous
- Abbreviations used in parameter names must be defined in the Glossary
- max - maybe just rename to
bufferSize
- Parameter names should neither be too long, nor too short
returnedName
-> name
/ nameBuffer
- Parameter names should be clear and unambiguous
Compatibility
(only in PRs)
- Symbol versioning is correct for breaking changes
- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine)
Parameter & Return Types
- Function parameters should use enum types instead of boolean types wherever sensible
- Wherever possible, function parameters should be
const
- Wherever possible, return types should be
const
- Functions should have the least amount of parameters feasible
Structural Clarity
- Functions should do exactly one thing
- Function name has the appropriate prefix
- Order of signatures in kdb.h.in is the same as Doxygen
- No functions with similar purpose exist
Memory Management
- Memory Management should be handled by the function wherever possible
- pass variable and return size instead
Extensibility
- Function is easily extensible, e.g., with flags
- Documentation does not impose limits, that would hinder further extensions
- nothing is written on maxSize < nameSize (would be fixed with memory management suggestion from above)
Tests
- Function code is fully covered by tests
- All possible error states are covered by tests
- All possible enum values are covered by tests
- No inconsistencies between tests and documentation
Summary
Different error codes for different errors
Other Issues discovered (unrelated to function)