{"id":58,"date":"2004-08-21T20:21:08","date_gmt":"2004-08-22T03:21:08","guid":{"rendered":"\/?p=58"},"modified":"2006-11-26T19:02:34","modified_gmt":"2006-11-27T02:02:34","slug":"always-document-your-output-parameters","status":"publish","type":"post","link":"https:\/\/www.slimjimmy.com\/weblog\/archives\/2004\/08\/21\/always-document-your-output-parameters\/","title":{"rendered":"Always document your output parameters."},"content":{"rendered":"<p>People writing C code often write functions that look like:<\/p>\n<pre class=\"example\">\r\n\/** foo -- Some function.\r\n  *\r\n  * PARAMETERS:\r\n  *   someInput       : Some input value.\r\n  *   OUT someOutputP : Set to some output value.\r\n  *\r\n  * RETURNS:\r\n  *   Some error code.\r\n  *\/\r\nerr_t foo(int someInput, data_t* someOutputP)\r\n{\r\n    err_t err = ERR_NONE;\r\n    \/* ..<!-- -->. Code goes here ..<!-- -->. *\/\r\n    return err;\r\n}\r\n<\/pre>\n<p>This isn&#8217;t good enough.  Callers have no idea what to expect if an error occurs.  Is <code>someOutputP<\/code>:<\/p>\n<ul>\n<li>in some totally undefined state?<\/li>\n<li>set to a known, bogus value?<\/li>\n<li>left untouched?<\/li>\n<\/ul>\n<p>This is particularly important if the function allocates some resources in <code>someOutputP<\/code> and the caller needs to clean it up.<\/p>\n<p>Whichever method you choose, you should choose one and document it.  It needs to be part of the function&#8217;s contract.  If left undocumented, callers can make assumptions about what state <code>someOutputP<\/code> is in, which is dangerous.<\/p>\n<p>Worse, if you don&#8217;t specify the behavior, someone who modifies the code later might not know what the behavior is supposed to be and is likely to screw it up.<\/p>\n<p>Better:<\/p>\n<pre class=\"example\">\r\n\/** foo -- Some function.\r\n  *\r\n  * PARAMETERS:\r\n  *   someInput       : Some input value.\r\n  *   OUT someOutputP : <strong>On success, set to some output value.<\/strong>\r\n  *                     <strong>On error, left untouched.<\/strong>\r\n  *\r\n  * RETURNS:\r\n  *   Some error code.\r\n  *\/\r\nerr_t foo(int someInput, data_t* someOutputP)\r\n{\r\n    err_t err = ERR_NONE;\r\n    \/* ..<!-- -->. Code goes here ..<!-- -->. *\/\r\n    return err;\r\n}\r\n<\/pre>\n<p>I&#8217;ll write my thoughts about the three behaviors later.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>People writing C code often write functions that look like: \/** foo &#8212; Some function. * * PARAMETERS: * someInput : Some input value. * OUT someOutputP : Set to some output value. * * RETURNS: * Some error code. *\/ err_t foo(int someInput, data_t* someOutputP) { err_t err = ERR_NONE; \/* &#8230; Code goes [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[],"class_list":["post-58","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/posts\/58","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/comments?post=58"}],"version-history":[{"count":0,"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/posts\/58\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/media?parent=58"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/categories?post=58"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.slimjimmy.com\/weblog\/wp-json\/wp\/v2\/tags?post=58"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}