{"id":319,"date":"2008-09-10T21:50:25","date_gmt":"2008-09-10T19:50:25","guid":{"rendered":"http:\/\/blog.m-ri.de\/?p=319"},"modified":"2008-09-20T15:21:36","modified_gmt":"2008-09-20T13:21:36","slug":"manche-ungenaue-dokumentation-nervt-einfach","status":"publish","type":"post","link":"http:\/\/blog.m-ri.de\/index.php\/2008\/09\/10\/manche-ungenaue-dokumentation-nervt-einfach\/","title":{"rendered":"Manche ungenaue Dokumentation nervt einfach"},"content":{"rendered":"<p>Die MSDN ist eines der gr\u00f6\u00dften und besten Nachschlagewerke, die ich kenne, allerdings gehen mir auch seine Unzul\u00e4nglichkeiten ab und zu auf die Nerven (und hier meine ich nicht die funktionellen Defizite, sondern die inhaltlichen)!<\/p>\n<p>Das sind dann ganz besonders die kleinen Sachen, die einem das Leben leicht machen k\u00f6nnten, die dann nicht &#8222;vollst\u00e4ndig&#8220; dokumentiert sind.<\/p>\n<p>Beispiel:<br \/>\nDie MFC List-Container (z.B. CObList). Wir lesen in der Doku zu <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/2fyts00d.aspx\">InsertAfter<\/a>:<\/p>\n<blockquote><p>position<br \/>\nA POSITION value returned by a previous GetNext, GetPrev, or Find member function call.<\/p><\/blockquote>\n<p>Gut! Aber da steht nichts zu <em>NULL<\/em>. \ud83d\ude15<br \/>\nAber wenn ich genauer dar\u00fcber nachdenken, kann <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/w231818s.aspx\">GetNext<\/a> und <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/k2y1x3s1.aspx\">Find<\/a> auch <em>NULL<\/em> zur\u00fcckgeben&#8230;<br \/>\nWas passiert also wenn ich <em>NULL<\/em> als Argument f\u00fcr <em>position<\/em>?<br \/>\nMein Verstand sagt mir: &#8222;Es wird ein\u00a0Element am Ende eingef\u00fchrt!&#8220; und ein Blick in den Code best\u00e4tigt den Verdacht.<\/p>\n<p>Warum steht in der Doku nicht gleich,\u00a0dass <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/2fyts00d.aspx\">InsertAfter<\/a> mit <em>NULL<\/em> als <em>position<\/em> ein <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/kdx8w9ds.aspx\">AddTail<\/a>\u00a0ausf\u00fchrt?<br \/>\nWer wei\u00df wieviele Entwicler solchen &#8222;unn\u00fctzen&#8220; Code aufgrund der mangelnden Doku geschrieben haben:<\/p>\n<pre lang=\"cpp\">CStringList lst;\r\nFillMyList(lst);\r\nPOSITION pos = lst.Find(_T(\"Anything\"));\r\nif (pos==NULL)\r\n    lst.AddTail(_T(\"Something to insert\"));\r\nelse\r\n    lst.InsertAfter(pos,_T(\"Something to insert\"));<\/pre>\n<p>Es w\u00fcrde ja gen\u00fcgen wie folgt zu schreiben:<\/p>\n<pre lang=\"cpp\">CStringList lst;\r\nFillMyList(lst);\r\nPOSITION pos = lst.Find(_T(\"Anything\"));\r\nlst.InsertAfter(pos,_T(\"Something to insert\"));<\/pre>\n<p>Korrespondierend ist die Doku von <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/h28xk22y.aspx\">CObjList::InsertBefore<\/a>\u00a0genauso unvollst\u00e4ndig.<br \/>\nWird NULL als Position verwendet wird hier ein <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/xt4h9bcy.aspx\">AddHead<\/a> ausgef\u00fchrt.<\/p>\n<p>PS: Mich \u00e4rgert auch jedesmal wenn einer meiner Kollegen solchen Code schreibt:<\/p>\n<pre lang=\"cpp\">CSomeObject *p = NULL;\r\n...\r\n\/\/ Conditional create\r\nif (SomeThing())\r\n     p = new CSomeObject();\r\n...\r\n\/\/ Cleanup\r\nif (p)\t\t\/\/ Category meaningless\r\n    delete p;<\/pre>\n<ol>\n<li>\n<div lang=\"cpp\">Warum der Test auf !=<em>NULL<\/em>?<\/div>\n<\/li>\n<li>\n<div lang=\"cpp\">Warum wird kein Autopointer verwendet, der das auch Exception-Save gemacht h\u00e4tte?<\/div>\n<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"<p>Die MSDN ist eines der gr\u00f6\u00dften und besten Nachschlagewerke, die ich kenne, allerdings gehen mir auch seine Unzul\u00e4nglichkeiten ab und zu auf die Nerven (und hier meine ich nicht die funktionellen Defizite, sondern die inhaltlichen)! Das sind dann ganz besonders die kleinen Sachen, die einem das Leben leicht machen k\u00f6nnten, die dann nicht &#8222;vollst\u00e4ndig&#8220; dokumentiert &hellip; <a href=\"http:\/\/blog.m-ri.de\/index.php\/2008\/09\/10\/manche-ungenaue-dokumentation-nervt-einfach\/\" class=\"more-link\"><span class=\"screen-reader-text\">\u201eManche ungenaue Dokumentation nervt einfach\u201c <\/span>weiterlesen<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[30,4,3,2],"tags":[370,138,352,55,136],"class_list":["post-319","post","type-post","status-publish","format-standard","hentry","category-c","category-mfc","category-programmieren","category-windows-api","tag-c","tag-dokumentation","tag-mfc","tag-msdn","tag-qualitaetssicherung"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/posts\/319","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/comments?post=319"}],"version-history":[{"count":1,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/posts\/319\/revisions"}],"predecessor-version":[{"id":320,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/posts\/319\/revisions\/320"}],"wp:attachment":[{"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/media?parent=319"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/categories?post=319"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/blog.m-ri.de\/index.php\/wp-json\/wp\/v2\/tags?post=319"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}