
\begin{DoxyItemize}
\item start = 2021-\/02-\/14 02\+:12
\item end = 2021-\/02-\/14 02\+:44
\item reviewer = Stefan Hanreich \href{mailto:stefanhani@gmail.com}{\texttt{ stefanhani@gmail.\+com}}
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1105}{}\doxysection{Signature}\label{md_doc_api_review_core_keyName_autotoc_md1105}
{\ttfamily const char $\ast$key\+Name(const Key $\ast$key)}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1106}{}\doxysection{Checklist}\label{md_doc_api_review_core_keyName_autotoc_md1106}
\hypertarget{md_doc_api_review_core_keyName_autotoc_md1107}{}\doxysubsubsection{Doxygen}\label{md_doc_api_review_core_keyName_autotoc_md1107}
(bullet points are in order of appearance)


\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} First line explains briefly what the function does
\item \mbox{[}x\mbox{]} Simple example or snippet how to use the function
\item \mbox{[} \mbox{]} Longer description of function containing common use cases
\item \mbox{[} \mbox{]} Description of functions reads nicely
\item \mbox{[} \mbox{]} {\ttfamily @pre} ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} \begin{DoxyPrecond}{Precondition}
key must be a valid key
\end{DoxyPrecond}

\end{DoxyItemize}
\item \mbox{[} \mbox{]} {\ttfamily @post} ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} \begin{DoxyPostcond}{Postcondition}
Pointer to key that can change over time
\end{DoxyPostcond}

\end{DoxyItemize}
\item \mbox{[} \mbox{]} {\ttfamily @invariant} ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} key name stays valid
\end{DoxyItemize}
\item \mbox{[}x\mbox{]} {\ttfamily @param} for every parameter
\item \mbox{[} \mbox{]} {\ttfamily @return} / {\ttfamily @retval} ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} add default return value to {\ttfamily @retval}
\end{DoxyItemize}
\item \mbox{[} \mbox{]} {\ttfamily @since} ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} add
\end{DoxyItemize}
\item \mbox{[}x\mbox{]} {\ttfamily @ingroup}
\item \mbox{[}x\mbox{]} {\ttfamily @see}
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1108}{}\doxysubsection{Naming}\label{md_doc_api_review_core_keyName_autotoc_md1108}

\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} Abbreviations used in function names must be defined in the Glossary
\item \mbox{[}x\mbox{]} Function names should neither be too long, nor too short
\item \mbox{[} \mbox{]} Function name should be clear and unambiguous ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} Function name might lead to confusions with {\ttfamily \mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}}}, make ~\newline
 their intentions more clear in their names
\end{DoxyItemize}
\item \mbox{[}x\mbox{]} Abbreviations used in parameter names must be defined in the Glossary
\item \mbox{[}x\mbox{]} Parameter names should neither be too long, nor too short
\item \mbox{[}x\mbox{]} Parameter names should be clear and unambiguous
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1109}{}\doxysubsection{Compatibility}\label{md_doc_api_review_core_keyName_autotoc_md1109}
(only in PRs)


\begin{DoxyItemize}
\item Symbol versioning is correct for breaking changes
\item ABI/\+API changes are forward-\/compatible (breaking backwards-\/compatibility to add additional symbols is fine)
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1110}{}\doxysubsection{Parameter \& Return Types}\label{md_doc_api_review_core_keyName_autotoc_md1110}

\begin{DoxyItemize}
\item Function parameters should use enum types instead of boolean types wherever sensible
\item \mbox{[}x\mbox{]} Wherever possible, function parameters should be {\ttfamily const}
\item \mbox{[}x\mbox{]} Wherever possible, return types should be {\ttfamily const}
\item \mbox{[}x\mbox{]} Functions should have the least amount of parameters feasible
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1111}{}\doxysubsection{Structural Clarity}\label{md_doc_api_review_core_keyName_autotoc_md1111}

\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} Functions should do exactly one thing
\item \mbox{[}x\mbox{]} Function name has the appropriate prefix
\item \mbox{[}x\mbox{]} Order of signatures in kdb.\+h.\+in is the same as Doxygen
\item \mbox{[}x\mbox{]} No functions with similar purpose exist ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} {\ttfamily key\+Unescaped\+Name} might be considered too similar
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1112}{}\doxysubsection{Memory Management}\label{md_doc_api_review_core_keyName_autotoc_md1112}

\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} Memory Management should be handled by the function wherever possible
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1113}{}\doxysubsection{Extensibility}\label{md_doc_api_review_core_keyName_autotoc_md1113}

\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} Function is easily extensible, e.\+g., with flags
\item \mbox{[}x\mbox{]} Documentation does not impose limits, that would hinder further extensions
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1114}{}\doxysubsection{Tests}\label{md_doc_api_review_core_keyName_autotoc_md1114}

\begin{DoxyItemize}
\item \mbox{[}x\mbox{]} Function code is fully covered by tests
\item \mbox{[} \mbox{]} All possible error states are covered by tests ~\newline

\begin{DoxyItemize}
\item \mbox{[} \mbox{]} empty key\+Name is not covered in tests
\end{DoxyItemize}
\item All possible enum values are covered by tests
\item \mbox{[}x\mbox{]} No inconsistencies between tests and documentation
\end{DoxyItemize}\hypertarget{md_doc_api_review_core_keyName_autotoc_md1115}{}\doxysection{Summary}\label{md_doc_api_review_core_keyName_autotoc_md1115}
\hypertarget{md_doc_api_review_core_keyName_autotoc_md1116}{}\doxysection{Other Issues discovered (unrelated to function)}\label{md_doc_api_review_core_keyName_autotoc_md1116}
