Identifier,Sentence,Category
Ind_19,"Extra annotation is done through the commit messages: each commit message must contain a reference to the issue tracking system, such that it is always clear in which context some code was changed.","LINK TO ISSUE TRACKER"
OSS_41,"I am a maintainer of SciPy. Together with NumPy we follow the guidelines given in https://docs.scipy.org/doc/numpy/dev/development_workflow.html#writing-the-commit-message and many more probably unwritten protocols.","LINK TO ISSUE TRACKER"
Ind_5,"we have a high level design document. autogenerated api docs such as doxygen, sphinx, or godoc. and we use comments as needed.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Ind_21,"We try to document high level design choices in the README.md file of the project. But we don't have policies.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Ind_22,"Not in code. Though architecture decisions on company level are captured with ADRs https://github.com/joelparkerhenderson/architecture_decision_record. Less strict `rules` are well documented outside of code, and hopefully thought of during code review.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Ind_40,"Also, if a commentscan be put into a format like JavaDoc, then use JavaDoc, as you can then generate a nice HTML page for it.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Ind_45,"Design choices have to be documented in the model of the SW architecture or detailed design.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Per_40,"Yes, doxygen style. For design choices, comment No active enforcement on this (so some code is not documented). In specific cases, we add @decision in comments (usually more than a one-liner).","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_9,"Yes, an architecture document should be created for any medium to large sized features describing the architecture and rationale.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_11,"Rarely, design and development quirks/choices to be collected in Wiki documentation","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_37,"Generally a dedicated docs directory with a per-subsystem document outlining the high level design and documented interfaces for easy navigation in an IDE.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_38,"* Detailed module level docstrings for developer documentation * Github wiki / markdown files for conceptual overview * Directory for notebooks for initial research and testing (code not used in production, but instructive for extensions and future reference).","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_40,"Numpy has both user documentation and detailed peer review discussions on GitHub.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_42,"Other than writing design docs for major features, no.","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
OSS_46,"design choices are documented outside code in separate document","ANNOTATE TO DESCRIBE HIGH-LEVEL DECIGN CHOICES"
Ind_5,"we have a high level design document. autogenerated api docs such as doxygen, sphinx, or godoc. and we use comments as needed.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_27,Use comments only if you need to explain something which is not immediately understandable by reading the code.,"ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_32,"However real life sometimes calls for exceptions, so you can defend and explain your need of annotations during code reviews and the team can raise suggestions or ideas on the topic at hand.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_34,"There are no specific policies in our code standard regarding this. However as a general rule any comment added to the source code should be meaningful. i.e. no obvious remarks or commenting old code when making design changes","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_40,"If comments are superfluous, a reviewer can ask to remove the comment, as it just distracts. For example /* If case x, do foo */ when the code is if (case ==x) { foo(); }","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_46,"Informal ones, to be peer-reviewed for adequacy","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_47,"Yes, where necessary comments should be added, but this is not closely monitored","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
OSS_2,"Generally most code is considered to be simple enough, and won't need documentation. When we feel something isn't straight foward (or when in doubt), we always add some code comments.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
OSS_3,"When something is complicated it should be commented.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
OSS_7,"Explanations are fine for more complex choices.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
OSS_28,"My policy is always to document any unusual design/implementation choices, or those that might be reusable in the future, especially for projects that might become public.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_6,"A Public procedure must be tested and documented.  Tricky implementations details must made public by a subpackage tested and documented as internals.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_32,"Generally speaking the only allowed comments are for some very dark and obscure snippets of code that cannot be refactored for better clarity (i.e. they don't logically make much sense on themselves but they do if you have a full picture of the business logic)""","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_9,"No. Everything is team dependent. There are more comments in the first few commits of a brand new component and these are gradually fixed in later commits.","DECISIONS LEFT TO THE TEAM"
Ind_19,"No policy within the organisation, but sometimes a policy within the team/project","DECISIONS LEFT TO THE TEAM"
Ind_40,"Pro-actively adding comments depends on the individual programmer.","DECISIONS LEFT TO THE TEAM"
OSS_8,"it depends on the developer and the cr reviewer","DECISIONS LEFT TO THE TEAM"
OSS_42,"We have no policies on in-line comments in source code. It is up to the developer to decide (I usually clarify non-obvious code). If something is unclear, another developer can ask for a clarification comment added to the source code during code review.","DECISIONS LEFT TO THE TEAM"
Ind_9,"No. Everything is team dependent. There are more comments in the first few commits of a brand new component and these are gradually fixed in later commits.","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
Ind_19,"In principle the code should be clean and clear such that no additional annotations are needed to understand the code.","NEVER ANNOTATE" 
Ind_24,"Our organization has just a traditional clean code policy with high endorsement of using annotations.","NEVER ANNOTATE" 
Ind_27,"Use comments only if you need to explain something which is not immediately understandable by reading the code.","NEVER ANNOTATE" 
Ind_32,"The agreement is that the code should speak for itself and if the design needs explanation then it's probably wrong and needs to go back to the drawing board.","NEVER ANNOTATE" 
Ind_33,"Code, combined with unit tests should be self-explanatory. If comments are needed to understand the code, that is a code smell.","NEVER ANNOTATE" 
Ind_40,"But if a pull request is reviewed and the reviewing programmer does not understand the code, then the reviewer will ask to simplify the code, or if that is not easily possible, add comments explaining the steps in more detail.","NEVER ANNOTATE" 
OSS_3,"Code should be self documenting.","NEVER ANNOTATE" 
OSS_17_6,"codigo fuente y diseño","NEVER ANNOTATE" 
OSS_23,"Code comments should be avoided. Code is documented by itself and appropriate unit tests. Following clean code principles and investing a lot of time into good naming of variables and functions is key.","NEVER ANNOTATE" 
Ind_6,"A Public procedure must be tested and documented.  Tricky implementations details must made public by a subpackage tested and documented as internals.","ALWAYS ANNOTATE"
Ind_19,"Interfaces should be fully documented (how to use the code).","ALWAYS ANNOTATE"
Ind_23,"no, we do soft (post-push) code review so if the code is not annotated enough, your colleagues/superiors will complain in person","ALWAYS ANNOTATE"
Ind_49,"Our coding standard makes it mandatory to describe/annotate every record, function signature and package but not every design decision.","ALWAYS ANNOTATE"
Ind_24,"Our organization has just a traditional clean code policy with high endorsement of using annotations.","ALWAYS ANNOTATE"
OSS_6,"Most high level classes are expected to be documented, specially how they fit into the whole picture, semantics around caller usage, thread-safety etc.","ALWAYS ANNOTATE"
OSS_44,"I'm currently on a project where 10% of each day is used to document the days work. Each method should have a java doc comment and each inline variable declaration should have a normal comment describing what it is going to be used for. Every loop should also have a normal comment above its declaration describing a typical execution scenario.","ALWAYS ANNOTATE"
OSS_5,"Best practices' are specified, but rarely defined. When they are they result in a maze of links which discourages reading them.","AVOID A LINK MAZE"
OSS_25,"Eslint restrictions, not using case insensitive names for components etc","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"
OSS_30,"https://www.tensorflow.org/community/contribute/code_style","ANNOTATE UNDER SPECIAL CIRCUMSTANCES"