GitHub - kkoomen/vim-doge: (Do)cumentation (Ge)nerator for nearly 20 languages 📚 Generate proper code documentation with a single keypress. ⚡️🔥
Any fool can write code that a computer can understand. Good programmers write code that humans can understand. -- Martin Fowler, 1999 We all love documentation because it makes our codebases easier to understand, yet no one has time to write it in a good and proper way. Vim-doge is a (Do)cumentation (Ge)nerator which will generate a proper documentation skeleton based on certain expressions (main
伸ばすのが難しい能力: 柴田 芳樹 (Yoshiki Shibata)
2018年6月1日に株式会社メルペイに入社して、4年が過ぎました。入社当時は、定年が60歳と聞いていたので、1年半の勤務だと思っていましたが、実際の定年は65歳であり定年まであと2年半です。 ソフトウェアエンジニアにとって重要な能力と（私は考えるが）、身に付けるのが難しいのが現実だと、この4年間で再認識したのは次の三つです。 開発の最初にAPI仕様をきちんと書けるソフトウェアエンジニアは少ない テストファースト開発を行っているソフトウェアエンジニアは少ないか、いない Tech Blogなどの執筆で、読み手を意識して、分かりやすい文章を書く、ソフトウェアエンジニアは少ない API仕様については、このブログでも何度か書いています（「API仕様を書く」）。テストファースト開発についても、「テストファースト開発」を書いています。分かりやすい文章については何も書いていないですが、「伝わる技術文書の書
プログラマーがドキュメントを書かない理由
この記事は、著者の許可を得て配信しています。 Why programmers don’t write documentation 最近ではずっとコードのドキュメンテーションに関連した記事を書いていたので、当然、私のMediumのおすすめ記事には「開発者がドキュメントを書かない本当の理由」という記事が表示されるようになりました。この記事では、ドキュメントを書くための優れたツールがないことが、ソフトウェアエンジニアが自分の作業や判断をドキュメンテーションする意欲を失わせる最大の原因について書いています。 私は普段、特定の記事を批判したりはしませんが、この記事には怒りを覚えました。このライターは図解ツールについていくつかメリットに関して述べてはいますが、全体的に誤解を招くような内容になっており、この重要な問題をより分かりにくくさせています。2つの図解ツールを比較して、どちらも不十分なツールである
JavaScript Primer 2.0 - ECMAScript 2020に対応した入門書を公開しました
ECMAScript 2020の変更に対応したJavaScriptの入門書としてJavaScript Primer 2.0.0を公開しました。 JavaScript Primerのウェブサイトから閲覧できます。 ウェブサイト: https://jsprimer.net/ サマリIssue: ECMAScript 2020の対応 · Issue #1145 · asciidwango/js-primer 変更内容の詳細はリリースノートを参照してください。 Release 2.0.0: ECMAScript 2020対応 · asciidwango/js-primer 2.0.0の目的 JavaScript Primerは、継続的にメンテナンスするためにOSSとして開発しています。 ECMAScriptの仕様は年に一度アップデートされていて、現実でのJavaScriptの使われ方も変化していく
docopt—language for description of command-line interfaces
Command-line interface description language docopt helps you: define the interface for your command-line app, and automatically generate a parser for it. docopt is based on conventions that have been used for decades in help messages and man pages for describing a program's interface. An interface description in docopt is such a help message, but formalized. Here is an example: Naval Fate. Usage:
Pythonのdocstring（ドキュメンテーション文字列）の書き方 | note.nkmk.me
Pythonでは、関数やクラスなどの定義の先頭に記述された文字列が、docstring（ドックストリング、ドキュメンテーション文字列）として扱われる。 IDEやエディタによってはキーボードショートカットでdocstringを表示させて内容を確認できる。またPyCharmなどでは、docstringの情報をもとに静的解析して警告を出してくれる。
PHPコードの解析をPhanからPHPStanに移行しようか検討しています - コネヒト開発者ブログ
こんにちは、サーバーサイドのお仕事してます金城(@o0h_)です。 7月は「波よ聞いてくれ」と「ベアゲルター」が共に出るという、嬉しい事態でした。沙村作品は魅力的なキャラクターがいつも多いですが、その中でも女性キャラの強さ・芯の太さに圧倒されます。 [まとめ買い] ベアゲルター さて、今回はタイトルの通り「(静的)解析どうするの」という問題について少し考えている事をまとめてみます。 「Phan」か「PHPStan」か、どっちが良いでしょうか？ 現在コネヒトではPhanを導入してコードをチェックしています。 「道具で安心感を得られる」のは最高なので、Phanもまた最高なのです。しかしながら、実際に日常的に回していく中で、いくつか気になっていることもあります。 実行に時間がかかる (プロダクトでは利用しない)php-astエクステンションが必要になる エラーが発生した時の原因箇所の特定が大変
Rustのこれまでとこれから | κeenのHappy Hacκing Blog
# Rustこれまでとこれから ---------------------- [Learn Languages 2018 in ODC (LL2018) ](https://llevent.connpass.com/event/95443/) === # About Me ---------  * κeen * [ちゅーんさんだよー](https://shindanmaker.com/789932) * [@blackenedgold](https://twitter.com/blackenedgold) * Github: [KeenS](https://github.com/KeenS) * [Idein Inc.](https://idein.jp/)のエンジニア + Rustで開発してるよ * Lisp, ML, Rus
NaNはNot a NumberだけどNumber型である話
この記事では、JavaScriptのNaNについて改めて学ぶという趣旨の話をします。 JavaScriptで、文字列などから数値へ値を変換したいことがあると思います。 典型的なケースでは、ユーザーに入力してもらった数字となる文字列を、Number型へ変換するというケースです。 この場合、Numberコンストラクタ関数やNumber.parseInt、Number.parseFloatなどが利用できます。(ここでは、Number.parseIntにしていますが、parseIntと同じです) // ユーザー入力を文字列として受け取る var input = window.prompt("数字を入力してください", "42"); // 文字列を数値に変換する var number = Number(input); console.log(typeof number); // => "number
Swift API Design Guidelinesの紹介(Swift 3版) - Qiita
Swift.org - API Design Guidelinesを読みながら日本語で書き起こしてみました。 (全訳では無く、また一部意訳など混ざっています。) API Design Gudelinesということで、例えばアプリ実装の特に画面側のコード書く際にはあまり気にしなくても良い気がするものも少し混ざっている気がしました。 原文に豊富にあるコード例はほとんど省いたので、適宜原文見た方が分かりやすいかと思います。 基本 用途が明確なこと 用途が明確なことは、最も重要なゴール。コードは書かれるより読まれることの方がずっと多い。 明確さは簡潔さより重要 短いコードを追い求め過ぎて、可読性など損なうのは良くない。 ドキュメンテーションコメントを書きましょう すべての定義にはドキュメンテーションコメントを書きましょう。 (訳注: 処理に添えるコメントではなくクラス・メソッド・フィールド定義など
いつ突然会社をやめても問題ないという基準でコードやドキュメントを書くテクニック - $shibayu36->blog;
blog.shibayu36.org 上の記事が思ったより読まれていたので、自分がこの基準を満たせるようにやっているテクニックも箇条書きで書いておく。 PullRequestを作ったら必ず自分でコードレビューをする コードを書いているとき、その一部一部はこれで完璧と思ってるけど、実は全体を見直すと分かりにくかったりする 1日寝てから見直す 1日経つとちょっと忘れて新鮮な気持ちで見れる 1週間後にもう一回見てみる 1週間くらい経つともうだいぶ忘れて、穴が見えてくる 穴があったら別PullRequestで直す もう一度同じところを担当することがあればチャンス。自分でもこれどういうことだっけってググり始めたら基準を満たせていない 自分が全く関わっていない部分のところを触りだしたらかなりチャンス。本当にまっさらな頭で基準を満たすか見れる。他人がやったことだからとか思わずにちゃんとその時に直す やっ
いつ突然会社をやめても問題ないという基準でコードやドキュメントを書く - $shibayu36->blog;
先に前提を話しておくと、会社は全く辞めるつもりはないし、むしろどんどん会社を良くしていこうと思っている。今回はそういう基準で自分がコードやドキュメントを書いていますよという話。 コードやドキュメントを書く時に、どのくらいきれいにしておくかとか、どのくらいわかりやすくしておくかとかを考えることがある。こんなとき僕は、いつ突然自分が会社をやめて連絡がつかなくなったとしても他の人がある程度理解できるか、を基準にしている。そのためにはあまりいい方法が思いつかなくて仕方なく書いている部分にはちゃんと経緯のコメントを書く。他にも例えば作ったサービスであるイベントを開催する方法のドキュメントを書くなら、全く何もやったことがない人がそのドキュメントを読んだらとりあえず開催できるよう、ドキュメントを書く。当然コードもかっこよさよりも、説明しなくても分かりやすくなるようなシンプルさを追求する。 また、このよう
StackOverflowが新サービス「Documentation」を開始。サンプルコードを中心に技術解説、質問されなくとも有用な情報を共同で作成
StackOverflowが新サービス「Documentation」を開始。サンプルコードを中心に技術解説、質問されなくとも有用な情報を共同で作成 StackOverflowは、エンジニア向けのQ&Aサイトとしてよく知られています。誰かが質問をすると、その答えを知っている人が回答する。質問をよりよくするために書き換えることもできるし、質問や答えの有用さを評価することもできて良い質問や良い答えはポイントが上がるなど、サイト全体のコミュニティの質が保たれるような仕組みを備えているのが特長です。 そのStackOverflowが、新サービス「Stack Overflow Documentation」（以下Documentation）をベータ版として公開しました（英語版StackOverflowにて。日本語版StackOverflowにはまだのようです）。すでにさまざまなトピックのドキュメントがあ
Ruby のココがダメ - Qiita
タイトルは釣りです。Ruby に盲目的に惚れている迂生には Ruby の痘痕（あばた）はエクボです。 それはともかく。 メソッド名の別名がありすぎ 「あなたは map 派？ それとも collect 派？」っていう問いがまず嫌い。 いや，別名にも意義があるとは思うんだけど，記憶の負担が大きい。 自分では map しか使わなくても，他人のコード読むんだったら collect を知っていなくちゃならない。 しばらく前に reduce っていうメソッド見て，そんなのあったっけ？と思ったら inject の別名だった。 map/collect と inject/reduce の名前とその背景にある発想については，Rubyist Magazine に良い記事がある： そうかと思えば，Array#delete_if と Array#reject! みたいに，働きは基本的に同じだけど，削除が行われなかっ
Python と型ヒント (Type Hints) - forest book
先日、Python の静的型チェッカーとして mypy を紹介しました。 mypy で静的型付け Python プログラミング - forest book 私には難しくてまとめきれないため、Guido が参照している漸進的型付け (Gradual Typing) も含め、また別の機会に、、、。 とか言っているうちに1ヶ月ほど経ってしまいました。 そうこうしているうちに PEP のドラフトも出てきたので区切りとしてまとめておきます。一通り調べたことを基にして書いていますが、私の誤解や勘違いもあるでしょうから怪しいところがあったら調べ直してみてください。もちろんツッコミも大歓迎です。 型ヒント (Type Hints) を導入するという提案 PEP 483 - The Theory of Type Hints | Python.org PEP 484 - Type Hints | Python
複数プロジェクトを抱えるチームでのデプロイ自動化
複数プロジェクトを抱えるチームでのデプロイ自動化 1つのチームで，10以上のプロジェクト，コードベースを抱える場合にどのようにデプロイの自動化を進めたか，工夫したこと，考慮したことなどをまとめておく． デプロイツールには，Python製のfabricを採用しているが，他のツールでも同様のことはできそう．なお，fabricの基本的な使い方などは既にインターネット上に良い記事がたくさんあるので書かない（最後の参考の項を見てください）． fabricの選択 シェルスクリプトとCapistranoを考慮した． まず，シェルスクリプトは人によって書き方が違うため，統一が難しくメンテナンスコストも高い．また共通化も難しい． 次に，Capistranoは，裏でやってくれることが多く，学習コストも高い．プロジェクトによってはかなり特殊な環境へのデプロイも抱えているため，Capistranoの前提から外れる
小飼弾、Swift愛を語る「2014年前半のインパクトは間違いなくSwift」 - エンジニアtype | 転職type
2014.08.18 スキル 業界で名の知れたプログラマーは、今年の上半期に何を学んでいたのか？ 「同業者が役に立ったものは、自分にも役に立つはず」という仮説を基に、彼らの学びlogから、2014年上半期の流れを振り返り、今後の動向を予想してみよう！ アルファブロガー 小飼 弾氏（@dankogai） 1969年生まれ。カリフォルニア大学バークレー校を経てオン・ザ・エッヂ（のちのライブドア）へ入社し、その後、取締役就任。96年にディーエイエヌを設立し、現職に。読書家としても知られ、ブログ「404 Blog Not Found」での書評は毎回、大きな話題を集めることでも有名。ニコニコ生放送にて、「プログラマー脳で今時のニュースを一刀両断する」放送を行っている。共著書、著書、多数 日本時間の2014年6月3日、WWDCの席上でAppleが新言語『Swift』を発表した。そしてその翌日の6月4日
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
http://tink.elliptium.net/2021/05/30/how_to_use_python_official_documentation.html
C++ 標準ライブラリ - C++ の歩き方 | cppmap
Kotlin style guide | Android Developers
