 So, I am Firuza Karmali, I work in the fundamental research group and I will be presenting on documentation and coding standards. So, first we will talk about documentation. So, what is documentation? It is nothing but a written record that based on the conversation that one or more persons have to document, to write it somewhere so that it can be referred later. You can have a hard copy earlier people used to write, now people write on the computer, why is it important? So, that it can be distributed to many people, it can be verified easily, it can be preserved. Say consider a scenario between a client and a developer. Now, the client says that I want to develop, I want our software to read my PDF documents. Imagine there is no PDF reader and right now the client is telling that I want a PDF reader which has some features like find and replace, bookmarking, annotating and sharing. So, the developer, he is also enthusiastic, so he starts developing and he develops fight and replace, bookmarking and sharing and while implementing annotating he finds difficult. So, he says I do not have any, there is no proof, ok nothing is written. So, I will tell the client that we never discussed anything about annotating and now when the meeting happens between the client and developer he presents these features and then annotating is not presented and then there is either a fight or then he has to develop later all those problems happen. Another option is that developer really genuinely forgets about a particular feature or a client feels that he has told something, but it was not done. So, for all these things if there is a written document it can be verified, so also suppose if the client and developer the usually these kind of meetings happen with the project leaders and the developers are different. Now, how will the project leader tell everything to the developers, if there is a documentation he can easily distribute to 100 people to 200 people, imagine telling this everything every meeting you keep on repeating the same thing it is difficult, so importance is to write. Now, what are the different types of software documentation? Requirement specification, function specification, technical documentation and the user manual. So, we come one by one. Requirement specification is generally written by the software developers based on the communication that has happened between the client to identify the requirements. Function specification as the term suggests is nothing but functionality, how to write, how to design a database, how efficient your interface should be, all those things when function specification, technical documentation it is for people to develop, so it is mostly for people who want to develop, extend the code say you have already you already have a PDF reader and you want people to collaborate, how would they collaborate if they do not know what is existing, if they do not know how you have written, so for that is the technical documentation. Your code is explained, your APIs are explained and then finally comes the user manual. User manual is for laymen users, for the people who will be using your product, like so if you want to find and replace how would you do that, so you click on view then you click find, you enter what is to be replaced with and then you have replace, so that goes into a user manual, no technical things go in a user manual. So now let's start by defining requirements, how many of you have heard this term, get good tomatoes, ok, mummy daddy they tell bhaiya ache tomato lekarana, ache bindi lekarana, get me good nice lady's fingers, ache watermelon, meetha watermelon lekarana, kesa bol sakta hai, it's very difficult, now for example my thinking of good tomatoes would be very different than that of my mother, but usually we get good tomatoes or good watermelon or good bindi, the reason is because we have been going along with our parents and we have been observing what my mother or what the elders are doing. If you tell somebody who is totally unaware of what a tomato is, it will be very difficult. So, can we redefine our requirements, so a better way of selling is get me bright red tomatoes, ok, so yeah, ok, so it should be red in color, bright red in color, lady fingers bring me long and thin lady fingers, ok, there was a incident in which usually sorry to say, but usually sons, men they don't go out for marketing, usually the ladies go out, so one of the incident was when my friend was asked to go to the market and get lady fingers, ok, he brought thick and big lady fingers, when he went home he got a scolding, no what did he know, he did not know what a lady finger is also, which are I went, chun chun ke usne bade bade aur thick bindi lekaran, go bhaji wala would have been very happy that all his bad bindi's have gone, so can we redefine and in watermelon how do you see it is a sweet watermelon, you know, vegetable wala wo watermelon ot hata hai aisa tuk tuk tuk tuk karata hai, haa meetha hai aur de deta aur aum luk glinal lekar bhi aata, isn't it, so how do you define a sweet watermelon, so can we redefine even these requirements we can redefine it better, so what does happen if there is lack of requirement specification, you will either get bad vegetable or you will either get a bad software, so requirement specification is very important, writing good requirement specification, another one is this is a project cartoon, so the customer explained it in that fashion wherein he requires a swing, there are three planks and he requires this kind of swing, now the project leader are not student in this way, the engineer designed it in this way, the programmer wrote it like this, the sales executive described it like a sofa, ok, how was the project documented, zero, no documentation, the operations installed in this way, the customer was highly build, the help desk supported it in this way and what the customer really wanted, he just wanted a tire tube on the tree, that's it, so what this clearly states that there is always a lack of communication between two people, between the clients and the developers and this should not happen, so if we write properly, this scenario will not happen, so software requirement specification it has introduction, overall description, specific requirements, system features and non-functional requirements, we come one by one, so under introduction, document purpose, why you developing the software, what is the importance, there will be a literature survey that XYZ software already exist, but these features are lacking, so we are developing a new software for XYZ purpose to enable the visually impaired, all to enable faster tracking or something like that, the scope of the project, what does it address, what does it enhance, the audience for whom the software is built, for children, for adults, for office goers, definition, acronym and abbreviations, if you are going to say the roles of a person, say there is a author in the system, there is a admin in the system, there are writers in the system, so what all, you may have some definition, you may have acronyms, say for example, he is a community admin, so he generally writes C A instead of writing big, so all those acronym, definition and abbreviations will go in this part, then comes the overall description, so in overall description, starting as a product overview, what we wrote in the scope of the project, we now expand it in more detail, functionality, we list down the features, find and replace, annotating, XYZ, we just list down, not in details just list of the features, implementation constraints, that is which technology will be used, we are writing in Java language, we are using these APIs, so suppose if somebody wants to enhance a system, what are the limitations, he has to use Windows OS, he has to use Ubuntu, all those things will go here, assumption and dependencies, what is needed to install the system, then comes specific requirements, so user interface, your wireframes, basically all the screens that will be there in your system, those will have to be put in user interface, functional requirements, list of features, but now with some more details, and then use cases, roles and responsibilities in the system, so I have some diagrams which I will show you, so this is a wireframe, it's a landing page of a particular website, wherein we say that there is a logo on the left, there is something called as communities, sign up and a login button, there is a carousel here with slideshow, something, there are some three articles in these blocks, there are some top contributors, in the photo there is contact us, FAQ, site map, there will be something similar for login, there will be something similar for writing something new or contributing, you know, all such small screens, whichever screens you have in your system, all those have to be designed and put it in the, design it as a wireframe. Now, coming to use case description, so the use case is registration, so what does one do in registration, so actors are, who are the users who will do it, anonymous users will register, not the existing users obviously, description, create an account on the platform is a description, then course of event, flow, how would the flow be, so action, he clicks on register, then action by the system, it displays the page, then user fills in the correct details and clicks create my account, then the system validates the information, displays registration is successful and sends an email to the user and blah, blah, okay, what are the preconditions and the post conditions, he should not be an existing user in the system, that's the precondition, post condition, user should be registered and logged in, okay, alternate flow, what is alternate flow, alternate flow is clicks on register, then action by the system is displays the page and then instead of registering through the system, he can register using Google or Facebook, other action is, clicks register, the system displays the page, but he fills in valid information, so the system validates the information, displays appropriate error messages and it goes to flow number two, so all those things are taken care of, so every minute details are documented in the use case description, now we'll show a use case diagram, so basically this is just an example, which are users are there in your system, say anonymous, authenticated, say community author, publisher, group publisher, group author, group admin, you do not bother right now of what these mean, but these are just some roles in the system, there could be any roles and then what is there, registration is there, FAQ is there, contact us and log in, log out and who is allowed to do what and registration it extends the request new password and using Google and Facebook, so everything that your system has, every page that needs to have a wire frame needs to have a use case description and a diagram, so let me go back to the presentation, so under specific requirements we write all these things, now system features, here we mentioned the features in detail, we elaborate on each and every feature that we would be doing, non-functional requirements, performance, how much of CPU is needed, how much of RAM, how much of space is needed to install the system, free space, you usually get when you install Ubuntu or any other system, so much of space will be utilized, don't we get that, we do get that, so why do we get that, so that we know that if I install the system, so much of space will go, so all those things will go in the performance, safety and security issues, what is to be done, if it's a hardware project, so usually when we read, when we buy a mobile, they usually say that okay, do not insert any other battery, insert only Lenovo batteries, all the safety and security would go here, so then comes the function specification and here we focus on the working of the system, it's a different document, where we mention the events, user will click here, user will click there, flow charts, your database schema, your entity relationship diagram, data flow diagram, all those things go here and it has meant for the developers, so the developers can develop the system in the manner prescribed in this document, then comes technical specification, wherein you have your code, you have your algorithms, you have the APIs mentioned, so it is for people who want to extend your system, who want to collaborate, unless you have this document, nobody else, no third party will be able to come and contribute to you, what is the point in writing something, which nobody will contribute back, generally now on GitHub, we have so many projects, all of them they provide technical specifications, APIs what do we mention, as Abhijit said, we should have a brief description, the methods are get, post, the URL, the parameters of URL, the permissions, so that if somebody wants to use a system without actually use your system, but they are not going to extend it, they want to use your system to get some information, so they will use APIs to do that, now we come to coding standards, so suppose I tell you that we need a system, what generally coders or even me would do, we take a computer and start writing, we start typing, without even searching on the internet, that such a system might even exist, so what we generally are advised to do by our seniors is to go on the internet, find out whether this functionality exists, whether the software exists, whether any module is there, which can help us do so, if so, we use them, we modify it, if it is not as per our needs, so we generally what do we do, we have to read a lot of code and if people write in different ways, suppose I write in a different way, somebody else writes in a different way, how would we interact, how would we know what that person has written, so we have to follow some set of guidelines while writing code, so that everybody understands, everybody can collaborate, everybody can come together, so that we can form a good community, so we follow some standards, now I will be discussing some standards related to Python, so every language will have different standards, Python will have different, Java will have different, so we have to follow the standards based on the language, programming language that we use, so PEP20 says readability counts, that's the points line of there, so consistency of the code in the project is more important, but in the module is very important, so guidelines are based on what, indentation, spaces and tabs, actually I was searching for an article which I had read long back about that there was a girlfriend and a boyfriend and they just split up because one was using spaces and one was using tabs, I really did not find that article, if I find I will put it up on our VK, then the naming conventions, the declaration, the statements, best practices do not do this, do not do that, we have to write less complex code so that others can understand, we have to refactor it regularly and we have automated tools for our code analysis and review, we need not do all these things, there are various tools like pylint for python, there are others for java and other languages, if you just write static code analysis tools on Wikipedia, you will get lots and lots of tools, if you are committing your projects to Git, you can have Git tools as well, so for our project we have used code factor which which rates the quality of our code, so sometime back our code was in B, now we have upgraded to A, so indentation using either four spaces in python, if the tabs are already existing then you prefer to use tabs whereas python 3 does not allow mixing of both, whereas python 2 was able to do that, now if you have to write long line of code and we have to wrap it, so we have to wrap it in like this, so result is equal to compute and where 3 will just go under this where, so as to improve the readability, there should not be more than 79 characters in a line, between two classes insert two blank lines, between each function insert one blank line, write every import on different lines, naming conventions, so for constants constants you should have all caps, for functions you have small case with an underscore, for class capitalize each word like community membership, so using specific exception instead of a bare accept, so the left hand side is avoid and the right hand side is follow, so when you say import a particular package you say try import some package and then you say accept some package is equal to none, so do not do this instead write accept import error, now unnecessary else after return, this is only true in python, so if you have a function to find the largest element, then you have your conditional statement if number 1 greater than number 2, return number 1 else return number 2, but here the else was not needed, because if I write return number 2 irrespective of if this statement does not execute it will naturally return number 2, then avoid using star for importing everything, because we will not know the other developers won't know what where have you called this particular module, if you specify then you will say he has called for this purpose, so avoid writings from dot models import star, write from dot models import community, so the other collaborators will know okay you have imported community for using, so he must be doing something with the community, otherwise if there are thousands of things written he will get confused, then checking for none, so instead of checking if message equal to equal to none or message not equal to run, you can just write if message is none or message is not none, so yeah this is the end of my presentation and I have some references the SRS template and the IEEE recommended practice of writing software specifications are taken from here, some Wikipedia articles are cited here coding conventions and requirements and then list of tools for static code analysis and some style guide and the project cartoon which I took any questions thank you