diff --git a/lectures/revealjs/07-documentation.adoc b/lectures/revealjs/07-documentation.adoc new file mode 100644 index 0000000000000000000000000000000000000000..ae79ee5100cd21d3aba884b39d62fad6415ec6be --- /dev/null +++ b/lectures/revealjs/07-documentation.adoc @@ -0,0 +1,175 @@ += Documentation +:customcss: slides.css +:icons: font + +++++ + <img id="main-logo" class="main-logo" src="images/template/main_logo_eng_no_text.png" width="300" alt="ntnu logo"/> +++++ + +[.smaller-80][.center-paragraph] +IT1901 Fall 2019 - 7th Lecture + + +[background-color = "#124990"] +[color = "#fff6d5"] +== Overview +[.smaller-80] +- Documentation +- Markdown +- Gitlab Flavoured Markdown (GFM) + + +[background-color = "#124990"] +[color = "#fff6d5"] +== Documentation + +== Documentation + +- is an important part of software development +- a way to ensure software quality +- several levels of documentation + + +== Types of documentation + +- Design documentation +- API specifications ( if applicable) +- readme files +- contribution guide +- frequently asked questions (faq) +- wiki +- comments ( including Javadoc ) + +== Who is reading the documentation + +- the developer him/herself +- other developers +- future maintainers of the software product +- external users (e.g. some provided API) +- others within the company / institution (testers, deployment ) +- .... + +== How is documentation improving the quality + +- allow new team members to be productive faster +- increase qualities such as maintainability and transferability +- saves time for both other contributors and initial dev + +== Readme files + +- give overview information regarding a project, subproject, module +- normally contains info about the role, contents, build details, dependencies and interactions with other parts / modules +- it is a way to provide needed contextual information that otherwise is not apparent from just looking at the source code + +== Comments (1) + +- allow adding documentatio in close proximity with the code +- they should not be a way to cope with bad naming or "special" assumptions in the code +- the standardized comments such as JavaDoc allow additional benefits such as code completion + +== Comments (2) + +[.center-paragraph] +image::../images/lecture07/code-comments.png[width=100%] + +[.smaller-40] +https://stfalcon.com/uploads/images/55c8bcff18b94.png + +== Comments (3) + +``` java + /** + * Creates a LatLong object from a String, using a specific separator. + * The format is <latitude><separator><longitude>. + * @param s the String to parse + * @param sep the separator + * @return the new LatLong object + */ + public static LatLong valueOf(final String s, final String sep) { + final int pos = s.indexOf(sep); + if (pos < 0) { + throw new IllegalArgumentException("No '" + sep + "' in " + s); + } + final double lat = Double.valueOf(s.substring(0, pos).trim()); + final double lon = Double.valueOf(s.substring(pos + sep.length()).trim()); + + return new LatLong(lat, lon); + } +``` + +== Over-documenting + +- documentation needs to be concise +- redundant documentation will result in maintenance overhead +- if some entity / operation is clear and self then it does not normally need additional documentation + +== ! + +[.center-paragraph] +image::../images/lecture07/comment-all.jpeg[width=400] + +[.smaller-40] +[.center-paragraph] +https://miro.medium.com/max/1138/1*Pyxsc7Uixbitv5myywaA_Q.jpeg (Gary Larson comic) + +[background-color = "#124990"] +[color = "#fff6d5"] +== Markdown + +== Markdown + +[.center-paragraph] +Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML.[8] Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. + +[.smaller-40] +https://en.wikipedia.org/wiki/Markdown + +== Markdown Syntax + +https://www.markdownguide.org/basic-syntax + + +[background-color = "#124990"] +[color = "#fff6d5"] +== Gitlab Flavoured Markdown (GFM) + +== Gitlab Flavoured Markdown (GFM) + +https://gitlab.stud.idi.ntnu.no/help/user/markdown + +++++ + <div id="footer" class="footer"> + <div style="display:table-row;"> + <span class="element" style="width:150px;"> + <a href="https://www.ntnu.no" target="_blank"> + <img id="footer-logo" class="footer-logo" + src="images/template/logo_ntnu.png" + alt="ntnu logo" height="28"/> + </a> + </span> + <span class="element" style="width:300px;">| IT1901 - 7th lecture </span> + <span class="element">| Documentation </span> + <span class="element"> </span> + </div> + </div> + + <div id="vertical-ntnu-name" class="vertical-ntnu-name"> + <span class="helper"></span> + <img src="images/template/vertical-ntnu-name.png" alt="Norwegian University of Science and Technology" /> + </div> + + <script type="text/javascript"> + window.addEventListener("load", function() { + revealDiv = document.querySelector("body div.reveal") + footer = document.getElementById("footer"); + revealDiv.appendChild(footer); + + titleSlideDiv = document.querySelector("div.slides section.title") + mainLogo = document.getElementById("main-logo"); + titleSlideDiv.prepend(mainLogo); + + vertName = document.getElementById("vertical-ntnu-name"); + revealDiv.appendChild(vertName); + } ); + </script> +++++ \ No newline at end of file diff --git a/lectures/revealjs/images/lecture07/code-comments.png b/lectures/revealjs/images/lecture07/code-comments.png new file mode 100644 index 0000000000000000000000000000000000000000..fa6d8cd237ec7f84e07602055ffbb5f54f146ed3 Binary files /dev/null and b/lectures/revealjs/images/lecture07/code-comments.png differ