Blank 2 - HackMD

--- tags: sprint, NASA, TOPS --- # Blank 2 Old outlines and notes from Lesson 2 ________________________________________________ ## DO NOT DELETE ANYTHING BELOW THIS LINE. WE ARE STILL REFERENCING IT AND THE VERSION IN BRAINSTORMING DOES NOT HAVE ALL OF THIS CONTENT. Old outlines for posterity if we didn't actually just consume all of the exact text for a section *yes, I agree with above - Babatunde* What does is mean for a software/code to be quality? - When someone comes across my code, what explanatory or descriptive overviews do they expect to see? - ReadME - Describes what the software does - How to install the software - When someone comes across my code, how do they expect to “install” it? What is packaging? How does this relate to “reproducibility”? - Options for installation: software repositories (what level of depth do we want here. I don't really see a way to touch this topic without going into specifics) - Links for language specifics (C, C++, Java, IDL, shell, bash, Python, [disciplines might have others]) - How to run your software - Might seem obvious for the developer, but not always simple for the user - Gives some usage examples - Describes the outputs - Details and notes, caveats, and the state of the software (Is it production ready or is it in alpha and a baseline code? Is it constantly maintained?) - How can issues/bugs be reported (if at all) - Contact information for the developer/researcher that wrote the software/code - List dependencies and computational environment - Useful links, DOI of publications that used or describe the software. - e.g. for sections in a README: https://link.springer.com/content/pdf/10.1007/s10664-018-9660-3.pdf (this is behind a paywall and I have no idea if it's useful. I literally can't read it. I don't have access.) - *ana: yes, they have a neat table for the classification they created to analyze READMEs, that we potentially could create a graph? Not sure if we can use it if it's not open though :(* https://drive.google.com/drive/folders/15wcUoh47BYkQBBu_k8UgR0ovcjSpMGNw?usp=sharing can you try the higher level? I'm not even sure what that means. I put that link in and it just says I don't have access. It's fine I've already written the section on READMEs. I did read their abstract and it appears to talk about classification schemes and how they can be helpful, but is probably out of scope at this point because it's about something extra that is beyond what is currently in practice. - Other resources (github, etc) - Operating system and/or browser the code should work in (compatibility) - Does the code work, for example, only work on Windows or Mac OSX? - If the code relies on the internet and has a visual interface, does the code depend on a particular kind of browser? Does the code use JavaScript? - License - Contribution instructions - Code of conduct - Dependencies - list what they are and what versions are being used - Example notebooks (This becomes language specific, perhaps just example code snippets/test cases) - When someone comes across my code, what example use-cases do they expect to see? Where and how are these useful? - Interactive notebooks can be useful tools to show additional usage examples for your users. - Journal/Research articles you've used this code in - It's important to make sure any publications you include in your documentation are not behind a paywall themselves; especially if they are fundamental to describing the software and how it works (This could be difficult and might not be always be possible, we can use "preferably") Maintenance - Did I just become a permanent maintainer? - It's not a requirement to maintain - How do I convey whether this code is actively maintained? (Why is this important?) - How do I deal with all of the requests for features/bug fixes etc I get? - What if I don't have continued funding for this project? - You don't have to continue - You can hand it off to someone else - You may be able to commercialize - Changes needed with funding (federal and private) to allow funding for continuous funding of widely used open-software - What are the responsibilities for maintaining the codes I've share? - How can I be more deliberate about my availability to maintain the codes I've shared? - How can I publish an open source tool without undertaking an open-ended responsibility to maintain it? - Etiquette in responding to requests from others. Clean Code *- There are many standards for coding (link to some examples) and each has their own philosophy on what constitutes "good" or "clean" code.* - Some important things to think about here is if someone else would be able to pick up and read your code and understand what it was doing. - Comments can be helpful for explaining the code, but are not always the necessary or correct solution. For example, sometimes the desired effect can be achieved simply with a more descriptive variable name. It should also be noted that in the context of web development, it is frequently the case that code to be deployed live is stripped off code ("minified version"). A distinction should therefore be drawn in the context of web development between code that is meant to guide other programmers versus what is actually deployed in reality - jQuery is a good example. - If you wouldn't know what was going on in your code if you left it for a year or two and came back, others probably can't understand it either. - As a user, --- what should a user without coding experience look for to know it's "good" code??? --- - Static code analysis is a tool that can help with reducing errors, performing quality control and increasing consistency (share resources? eg. https://the-turing-way.netlify.app/reproducible-research/code-quality.html) - It's beneficial to conform to accepted programming conventions - for example, some languages use camel case for variable names. - Do not use names for variables, functions and the like that are likely to be keywords in one or more programming languages. Examples include "while", "null", "for", etc. - If the code relies on an external file, the external file should have a filename that is easily understandable within the context of the code. * --> **Note from Taher**: Automatic code quality review tools are different than static checks. For example, check: I still think these may be out of scope and we are headed into territory of specific tools and/or software development rather than discussing open software best practices. Again, we are trying to keep the quality and cleaniless of code to a top level overview discussion that centers around readability for outside users. **Taher**: What I meant was that we can say: There are some tools that can help with improving the code quality. These tools are often automated and can be easily integrated with code repository services. Some examples of such services are [pre-commit](https://pre-commit.com), [sonarcloud](https://sonarcloud.io), [codefactor](https://www.codefactor.io), and [lgtm](https://lgtm.com).