Pleasanterのコードスタイル コメント編

Pleasanter開発チームのいしざきです。

PleasanterはオープンソースのWebデータベースでGitHubにソースが公開されています。

今回はPleasanterへプルリクエスト(PR)する際に気にしたいコードスタイル コメント編です。

よく見るスタイルとPleasanterの比較

次の例はよく見るコードルールで書かれたC#クラスです。このクラスがPleasanterではどうなるか見てみましょう。
(コードは空白行編と同じものです。)

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace SampleApp
{
    public class PopularStyleClass
    {
        public async Task<string> GetDataFromWeb()
        {
            // Create HttpClient
            var httpClient = CreateHttpClient();
            httpClient.Timeout = new TimeSpan(TimeSpan.TicksPerSecond * 20L);

            // Request Data
            var contentData = "<contentData>";
            var requestContent = new StringContent(contentData);

            // Post
            var responceMessage = 
                await httpClient.PostAsync("<requestUrl>", requestContent);

            // Responce Data
            var responceContent = responceMessage.Content;
            var responceData = await responceContent.ReadAsStringAsync();
            return responceData;
        }

        HttpClient CreateHttpClient()
            => new HttpClient();
    }
}

Pleasanterでは次のようになります。
(※筆者も勉強中のため100%正しいPleasanterのスタイルではないかもしれません。勉強のためにこの記事を書いている面もあります)

using System;
using System.Net.Http;
using System.Threading.Tasks;
namespace SampleApp
{
    public static class PleasanterStyleClass
    {
        public static async Task<string> GetDataFromWeb()
        {
            var hc = CreateHttpClient();
            hc.Timeout = new TimeSpan(ticks: TimeSpan.TicksPerSecond * 20L);
            return await (await hc
                .PostAsync(
                    requestUri: "<requestUrl>",
                    content: new StringContent("<contentData>")))
                .Content
                .ReadAsStringAsync();
        }

        private static HttpClient CreateHttpClient()
        {
            return new HttpClient();
        }
    }
}

Pleasanterのコメント

Pleasanterのコメントはメソッドの内部には一切書きません。
また他の場所でもごく一部の特別な例外を除いて、一切書きません。例えば次のようなメソッドのドキュメンテーションコメントが例外の一例です。

/// <summary>
/// Fixed:
/// </summary>
private void OnConstructed(Context context)

このドキュメンテーションコメントは見かけたら消さずに残してください。

PRのお願い

PleasanterへのPRいただける際にはコメントはなしでお願いします。
また、メソッド内部のコメントを見つけた方、ぜひ修正してPRお願いします。

その他のコードスタイル

今回のコード例だけでもコメント以外にも様々なコードルールが読み取れますが、Pleasanterは日々進化中でPR時のお願い事項などの整備は取り組み中の状態です。

不定期になりますが今後も少しずつこちらのブログで紹介してまいります。今後PRするかもしれないという方、継続してチェックしていただけると嬉しいです。