You can share the code with git, but where and in what format do you share the specifications?

Asked 2 years ago, Updated 2 years ago, 44 views

We decided to develop the software in a group of school club activities.
Now that I know that the source code I wrote can be done by a version control system such as GitLab, I've decided.

Next, I think we need to share the software rules somewhere.
We have proposed a group function of LINE or twitter, or a whiteboard, but we understand that there are some difficulties like the following.

  • Group functionality makes information messy and troublesome to organize later
  • The whiteboard cannot be read without the board, and if you accidentally turn it off, it cannot be undone
  • Both of them will be unmanageable if there are many rules

I looked into what tools I generally use, but I couldn't find anything called "This is it!"

git

2022-09-30 15:56

3 Answers

Common software developments in the enterprise use a variety of tools to properly manage rules, conventions, development history, issues, progress, etc.
Because large software developments involve dozens (and possibly hundreds) of customers, sales, managers, developers, testers, etc., sharing and maintaining the latest information above can quickly break down without knowing who's doing what.

Some companies use Twitter and LINE to communicate, but only a few manage important issues such as development rules and issues.
As you notice, the log flows quickly, so the ability to look back on past conversations is weak and the use of albums and notebooks is limited.

The focus of your question is group functionality and rule sharing on the whiteboard, so it's out of scope, but I'll give you an example of what tools general software development uses to share and check rules and development information.

  • General Development Rule Management
    • Wiki (Gitlab Wiki, Redmine, PukiWiki, etc.)
    • Online file sharing (Google spreadsheets, Dropbox, etc.)
      Write "Promise Development" such as "Let's commit after development" and "Let's write the issues in Issue (described later)."
      In many development sites, wikis are used for easy document tiering and retrieval.
      Some companies use Excel or words to manage the rules in bullet points in order to publish them as explanatory materials to partner companies.(Personally, I do not recommend it because of the high cost of searching and writing.)
  • Coding Rule Management
    • Static analysis to monitor coding conventions (ESLint, StyleCop, etc.)
    • Format tools (IDE included, gofmt, etc.)
      Manage how to write code such as "Tab 4 spaces" and "Variable names start with lowercase letters and method names start with uppercase letters."
      Major programming languages provide tools to automatically parse and find rule violations with parser generators such as Yacc.
      When using these tools, the recommended operation is to follow the tool standard settings without changing them.
      If you customize and stick to your own rules, developers tend to feel dissatisfied and uncomfortable because they don't know why.
  • Continue Management
    • Ticket management issues (GitLab Issue, Microsoft Teams, etc.)
    • Development Calendar (Microsoft Teams, Redmine, etc.)
      It is a tool to share and manage response status and development progress by ticketing bugs and additional functions such as "If you type in this condition and press the button, you will get an error" and "Create a data transmission function by the 11th."
      You can see at a glance who is responsible for which feature development and how it works, and can also be used to code-review where each ticket is added according to the rules.
      I think it's almost an essential tool for current corporate development (there's also a development method called Ticket Driven Development), so even if you don't know how to use it at first, I recommend you to try using GitLab Issue for now.
  • Source Code Complexity Measurement
    • Measure code metrics (plato, Visual Studio standard, etc.)
      It analyzes and visualizes source code filth, such as "almost the same content is copied into 10 source files" and "50 nested if statements."
      You can pick up the visualized content and make it into a rule like "Use the common method hoge() when connecting to the database" or follow newcomers who are not good at coding.
  • Continuous Integration
    • CI/CD tools (Circle CI, Jenkins, etc.)
      It is a powerful tool behind the scenes that automates commitments and timers that takes several minutes to do manually such as "I want to analyze static every time I commit" and "Mr. A changed the common function, and there was a compilation error on the screen created by Mr. B."
      It is not directly related to the rules, but they automatically do things like visualization of rules, unit tests, and code metrics measurements, and report abnormalities through chat tools, which help us follow the rules and develop them.
      The key to this operation is CI/CD tools that report warnings and errors, and then fix them quickly without ignoring them.
      When warnings become normal, no one responds to critical errors thinking "again."
  • Communication
    • Chat (e.g. Slack)
      "I don't understand this, but please let me know who it is," "How about the presentation design, layout like the attached rough image?" and so on.
      It is difficult to distinguish between issues, but it is useful for sharing incidents/ideas and small consultations that are clearly independent issues.
      You can use it in development by looking back at the ideas that are excited by the group and making them into rules.
      Slack is good at searching and grouping, and it can monitor programs using bot, so many companies are using it.
  • Agile development
    • Cambang style (whiteboard, etc.)
      Attach "ToDo", "Doing", and "Done" sticky notes on the whiteboard to visualize remaining issues, work in progress, and this week's results.
      Personally, I think whiteboard is a good tool for writing rules in the early stages of development.
      It's hard to use if you have development members who are remote working long distances, and you need to compile your decisions into wikis and so on, but it's useful if you don't use them wrong because they cost less to start writing and browse, physically limited space.
      "Since the word ""whiteboard"" came out, we added the keyword ""agile development"" which is famous as a software development method."
  • Wiki (Gitlab Wiki, Redmine, PukiWiki, etc.)
  • Online file sharing (Google spreadsheets, Dropbox, etc.)
    Write "Promise Development" such as "Let's commit after development" and "Let's write the issues in Issue (described later)."
    In many development sites, wikis are used for easy document tiering and retrieval.
    Some companies use Excel or words to manage the rules in bullet points in order to publish them as explanatory materials to partner companies.(Personally, I do not recommend it because of the high cost of searching and writing.)
  • Static analysis to monitor coding conventions (ESLint, StyleCop, etc.)
  • Format tools (IDE included, gofmt, etc.)
    Manage how to write code such as "Tab 4 spaces" and "Variable names start with lowercase letters and method names start with uppercase letters."
    Major programming languages provide tools to automatically parse and find rule violations with parser generators such as Yacc.
    When using these tools, the recommended operation is to follow the tool standard settings without changing them.
    If you customize and stick to your own rules, developers tend to feel dissatisfied and uncomfortable because they don't know why.
  • Ticket management issues (GitLab Issue, Microsoft Teams, etc.)
  • Development Calendar (Microsoft Teams, Redmine, etc.)
    It is a tool to share and manage response status and development progress by ticketing bugs and additional functions such as "If you type in this condition and press the button, you will get an error" and "Create a data transmission function by the 11th."
    You can see at a glance who is responsible for which feature development and how it works, and can also be used to code-review where each ticket is added according to the rules.
    I think it's almost an essential tool for current corporate development (there's also a development method called Ticket Driven Development), so even if you don't know how to use it at first, I recommend you to try using GitLab Issue for now.
  • Measure code metrics (plato, Visual Studio standard, etc.)
    It analyzes and visualizes source code filth, such as "almost the same content is copied into 10 source files" and "50 nested if statements."
    You can pick up the visualized content and make it into a rule like "Use the common method hoge() when connecting to the database" or follow newcomers who are not good at coding.
  • CI/CD tools (Circle CI, Jenkins, etc.)
    It is a powerful tool behind the scenes that automates commitments and timers that takes several minutes to do manually such as "I want to analyze static every time I commit" and "Mr. A changed the common function, and there was a compilation error on the screen created by Mr. B."
    It is not directly related to the rules, but they automatically do things like visualization of rules, unit tests, and code metrics measurements, and report abnormalities through chat tools, which help us follow the rules and develop them.
    The key to this operation is CI/CD tools that report warnings and errors, and then fix them quickly without ignoring them.
    When warnings become normal, no one responds to critical errors thinking "again."
  • Chat (e.g. Slack)
    "I don't understand this, but please let me know who it is," "How about the presentation design, layout like the attached rough image?" and so on.
    It is difficult to distinguish between issues, but it is useful for sharing incidents/ideas and small consultations that are clearly independent issues.
    You can use it in development by looking back at the ideas that are excited by the group and making them into rules.
    Slack is good at searching and grouping, and it can monitor programs using bot, so many companies are using it.
  • Cambang style (whiteboard, etc.)
    Attach "ToDo", "Doing", and "Done" sticky notes on the whiteboard to visualize remaining issues, work in progress, and this week's results.
    Personally, I think whiteboard is a good tool for writing rules in the early stages of development.
    It's hard to use if you have development members who are remote working long distances, and you need to compile your decisions into wikis and so on, but it's useful if you don't use them wrong because they cost less to start writing and browse, physically limited space.
    "Since the word ""whiteboard"" came out, we added the keyword ""agile development"" which is famous as a software development method."

Since the development of club activities is short between individuals and probably mainly works in the club room, it would be better for developers to use CI tool to check the rules, set weekly goals using ticket management and Kanban.

The above sentence is difficult because it's only horizontal characters, but I won't explain it because it's too far off the rails when I expand to Agile development.
If you are interested, please use it as a keyword to find out for yourself.

Finally, if you have developed a rule and decided to deploy a tool, make sure that anyone can always tell you why you create it and use it.
Even if the person who introduced the product thinks it is good for improving the quality and speed of development of the product, the person who uses it may feel that it is simply compulsory if they do not understand the benefits.
There is also a side effect of reducing volume by limiting it to rules and tools that can be clearly explained.

It may be easier to use the tools that seem useful to you if you first try them on a small group and then have an environment where everyone can use them before publishing them.
A tool that no one else uses is often a technical liability, but you can get the most out of it by actively using it as an "essential" tool.

Please do your best to complete the software.(I think the most important thing in software development is completion rather than following the rules)


2022-09-30 15:56

If you only want to share information among certain users, there are several possible candidates.

  • Online Storage
    Google Drive and Dropbox allow you to sync/share any file, but so-called
    like docx You can also edit the "Office Format" file directly on your browser.

  • Digital Notes
    Evernote and OneNote will be more like a whiteboard.

Online Storage
Google Drive and Dropbox allow you to sync/share any file, but so-called
like docx You can also edit directly on your browser by registering a "office format" file.

Digital Notes
Evernote and OneNote will be more like a whiteboard.

(Additional)
It may be a little difficult to build an environment, but if you're looking to share source code with Git in the future, Redmine tickets and wikis are one of the candidates.


2022-09-30 15:56

  • Just like the source code, rules are created in a text file (such as a markdown format) and Git version is managed.
  • wiki.(Some are independent, but they also come with the GitLab and GitHub services.)
  • Online office suite, if you want multiple people to edit at the same time and share your editing results in real time, it might be great.


2022-09-30 15:56

If you have any answers or tips


© 2024 OneMinuteCode. All rights reserved.