{"action":"opened","issue":{"url":"https://api.github.com/repos/MOxUnit/MOxUnit/issues/29","repository_url":"https://api.github.com/repos/MOxUnit/MOxUnit","labels_url":"https://api.github.com/repos/MOxUnit/MOxUnit/issues/29/labels{/name}","comments_url":"https://api.github.com/repos/MOxUnit/MOxUnit/issues/29/comments","events_url":"https://api.github.com/repos/MOxUnit/MOxUnit/issues/29/events","html_url":"https://github.com/MOxUnit/MOxUnit/issues/29","id":166194778,"number":29,"title":"Commenting style suggestions/rationale","user":{"login":"jwleblan","id":18444819,"avatar_url":"https://avatars.githubusercontent.com/u/18444819?v=3","gravatar_id":"","url":"https://api.github.com/users/jwleblan","html_url":"https://github.com/jwleblan","followers_url":"https://api.github.com/users/jwleblan/followers","following_url":"https://api.github.com/users/jwleblan/following{/other_user}","gists_url":"https://api.github.com/users/jwleblan/gists{/gist_id}","starred_url":"https://api.github.com/users/jwleblan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jwleblan/subscriptions","organizations_url":"https://api.github.com/users/jwleblan/orgs","repos_url":"https://api.github.com/users/jwleblan/repos","events_url":"https://api.github.com/users/jwleblan/events{/privacy}","received_events_url":"https://api.github.com/users/jwleblan/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2016-07-18T21:12:10Z","updated_at":"2016-07-18T21:12:10Z","closed_at":null,"body":"While working on changes as part of a pull request to improve assertExceptionThrown.m I noticed some places that comments could be improved.  That is, made more clear and readable.  Few things can be more annoying that someone deviating from a projects commenting style/guidelines without discussion so here goes...\r\n\r\nI feel as though the projects commenting style can be altered to improve readability/clarity.  The suggested changes (or at least allowances) are all based on making things more explicit.  Specifically:\r\n\r\n- Place all comments above `function …` .  This prevents a functions documentation from being split between two blocks of executable code and groups the executable code into a single coherent block.  It also allows one to collapse a functions implementation while maintaining that functions documentation.  Finally, it prevents users from treating the function declaration itself as the documentation of its prototype rather than the one provided in the comments.  The commented prototype is often much more expressive (see below)\r\n- Use \"\"<>\"\" rathe than \"\"[]\"\" to indicate optional parameters.  Square brackets indicate concatenation in Matlab, and this could lead to confusion for less experienced users.\r\n- All caps section headings.  The use of all capitols for section headings, and the explicit inclusion of a SYNTAX heading, could make documentation more easily parseable by eye.\r\n- The addition of a PURPOSE section.  A functions summary description (available in the first comment line) is often insufficient for describing what a function is for.  A dedicated purpose section would allow for this, and its inclusion would encourage better documentation.\r\n- The addition of an ASSUMPTIONS section.  A place to explicitly state assumptions.  For example, functions often do not provide input argument checks.  This is a good thing, for \"internally facing functions\" as it allows the code to execute faster, but when this is the case it ought to be explicitly stated.\r\n- A visual \"-\" would be helpful in indicating where multi-line parameter descriptions start.\r\n- 80-character bars as a visual indicator that we expect comments to be formatted within this width limitation.\r\n- Place comments inside a block comment to allow them to be collapsed in more advanced editors\r\n\r\nThe only downside I can see to these changes is that Octave has a limitation in its help parser that fails to recognize block comments.  One can either remove this feature, or accept Octave's limitation until it gets fixed.\r\n\r\nAn example of these ideas being put into practice can be found in assertExeptionThrown.m in the aforementioned PR."}}
{"actor":{"display_login":"jwleblan"}}