非プログラマーにコードを表示する最良の方法
請求書の印刷を担当するプログラムを分析するように求められます。 （SAPスクリプト経由）
このプログラムはかなり古く、4,000行を超えるコードが含まれています。それは多くの異なる条件下で多くの異なる変数を設定します。幸いにも、コーディング自体はそれほど難しくありません（if/else、ケース、ループがたくさんあります）。ある種の「コンパイラ」を記述して、これを依頼した人が理解できるものにコーディングを変換できると思います。
基本的に、ドキュメント/プログラム/ Excelシート/「印刷された価格フィールドにVATが含まれるのはどのような条件ですか？」のような質問に答えられるものは何でも書きたいのですが。 /「どのデータベーステーブルが住所フィールドを埋めますか？」
コーディングのどの部分が特定の変数に影響するかを視覚化する必要があります。現在、変数自体から始まり、すべての「IF」、「LOOP」などをたどっていく、ある種の「逆ツリー」が仕事を成し遂げるかもしれないと思います。
これは良いアイデアだと思いますか、これを視覚化するための別の提案がありますか？
@Jeroenが示唆したように、私の問題をもう少し明確にするために：
- プログラム全体に及ぶものを作成する必要があります。つまり私のユーザーは、他の人に尋ねたり、ABAPコードの読み方を学んだりせずに、プログラムのどの部分でも興味があることを理解できるはずです。
- 今の私の最大の問題は、さまざまな変数の視覚化LOTを理解しやすく、ナビゲートしやすい方法でプログラムの流れを視覚化することです。
これを行う最も簡単な方法は、MS Visioまたはその効果を使用したフローチャート図を使用することです。
Visustin-Visioへのエクスポートのページにあるようなものに見えるかもしれません ：
コメントに基づく編集：
@ Sharkyがコメントで言ったように、「疑似コードを追加することもできます。」
これは、もしあなたが知らなければ、ハイレベルな用語しか理解できない幹部のための英語を意味します。
それはこのように見えますAlex彼の記事App Inventorが作成されました：
2つを組み合わせて実行することもできます。すべてのコードを図にしようとすると、プロジェクトのサイズによっては、非常に大きくなる可能性があります。それはあなたが本当に取得したい粒度に依存します。
あなたは考える必要があります、私はプレゼンテーション/ UIレイヤーだけを行うつもりですか、それともビジネスロジックレイヤーも含めますか？そして最後にサービス/データレイヤーはどうですか？これらすべてを足し合わせると、プロジェクトによっては膨大になる可能性があります。とはいえ、4k行程度だと言ったので、疑似コードと実際のコードを混同することは悪い考えではないかもしれません。
または...
コードを文書化した場合、そこにプラグイン/アドイン/ソフトウェアがあるかもしれません（確かにあります）。これにより、ヘルプ/ドキュメントガイドが自動的に作成されます。次に、いくつかの疑似コードVisioダイアグラムをコメントの視覚的表現として混在させることができます。あなたは周りを見回して、あなたが見つけることができるものを見る必要があるだけでしょう。無料の場合もあれば、少額の場合もあれば、多額の場合もあります。
私の意見では、それはあなたのすべてのベースをカバーし、それがすべてを混ぜ合わせ、それがプログラマーであれ高レベルであれそれを読む人に適しているので、それはおそらくあなたのすべてのベースをカバーし、おそらく最良の選択肢であるので、それは価値があります幹部またはその間の誰か。
最も重要なものから始めましょう。ソリューションの成熟度を確認するための簡単なチェックリストを次に示します。
- resultを特定のコードに対して自動生成できますか？
- 追加の「調整」を必要とせずに継続的に更新できますか？
- ソリューションは確定的でシンプルなレイアウトをサポートしていますか？
- 3つまたは4つのオプションを持つ単純なswitch-caseを視覚化できますか？
- バージョン管理を処理し、2つのバージョン間の違いを視覚化できますか？
これらの "要件"はやり過ぎに見えるかもしれませんが、それがないと、最終的にユーザーはコードに対処することを余儀なくされ、すべての豪華な視覚化ツールが役に立たなくなります。とにかく、自由形式のフローチャートのアイデアを確認してみましょう。ここに8年前の自由形式のDSL構造の視覚化があります：
確認してみましょう：
- できますが、アイテムを適切にレイアウトするのは本当に難しいので、ユーザーは構造を調整する必要があります。
- 可能性はありますが、レイアウトが壊れる可能性が高いです。
- いいえ、ノードをレイアウトするには多くの方法があり、ユーザーが確実にアクセスできないようにするために、いくつかの特別な記事（たとえば、クリストフブーフハイム、マイケルジャンガー、セバスチャンライパートによる線形ツリーでのルート化ツリーの描画など）を調査する必要があります構造が現れるまで数秒待ちます。
- 番号。
- いいえ。レイアウトは複雑であるため、current構造とprevious構造を比較するのは非常に困難です。
以下に私の経験を要約してみます。私は単に楽しみのためにそれをしているので、この答えを無視してください。
教訓
上記の例は、かなり複雑なネットワークプロトコルデコードロジックの視覚化を示しています。それは単純であるにもかかわらず、それでもまともな高レベルの概要と簡略化されたナビゲーションを提供します。問題は、構造全体を読みやすくするために、ユーザーが要素を適切にレイアウトする必要があることです。
- レッスン1：ほとんどすべてのフローチャートの例は、シンプルであるため読みやすいように見えます。実際の構造はもっと複雑なので、対応するフローチャートも複雑になり、ユーザーがそれらの構造を読むのを助けるために多くの追加のトリックが必要になります。
レッスン2：ユーザーは、愚かなレイアウトを行うために貴重な時間を費やすことを好みません。
レッスン3：ユーザーが作成したレイアウトは、システムで変更しないでください。
したがって、非常に重要な結論があります。ユーザーがレイアウトに煩わされるのを避けてください。また、いくつかの非常に貴重なルールがあります。
コミュニケーションデザイン：設計および計画のためのWebサイトドキュメントの開発
その本には興味深いヒントがたくさんありますが、適切な方向を選択することの重要性を強調したいと思います。当然、キャンバスを使用して、必要なものを描画し、ユーザーがそれをドラッグできるようにすることもできますが、すべてを単純化して、通常のスクロールパターンに従う方が良いです。
チェック D3.jsドラッグアンドドロップ、ズーム可能、パン、自動サイズ変更可能な折りたたみツリー
ところで、 Nassi–Shneidermanダイアグラム と呼ばれる古典的で単純なフローチャート表現があります。
そのようなアプローチの現代的な実装は非常に便利かもしれませんが、それは依存します。私はそれが最初から非常に簡単で直感的に見えないに違いない:)
代替案
フローチャートは唯一のアプローチではありません。少し見てみましょう。すでに利用可能な多くの異なるソリューションがあります。チェックしてください ビジュアルプログラミング
私はチェックすることをお勧めします：
そこには魔法はありません。初期の複雑さがあれば、間違いなく後でわかります。
拡張フローチャート
ウィキペディアには単純な フローチャートの例 があります。これを使用して、提案されたアプローチを示します。
特別なことはしません。レンダリングを単純化し、それを均一かつ柔軟にする方法についての簡単なアイデア。
これはアイデアを説明するためのワイヤーフレームのようなものです。要素はクリーンで読みやすいです。フローの識別とフローのナビゲートは簡単です。
レンダリングは確定的であり、非常に簡単です。基本的には、列と行がすべてです。
スイッチケース構成が可能です
実行フローは簡単に追跡できます
要素をグループ化できます
列と行は折りたたむことができます
場合によっては、「フローストレッチ」が必要になる場合があります
他のいくつかのケースでは、読みやすくするためにフローストレッチを使用できます。
バージョン管理と差分
確定的で安定したレイアウトがあるため、同じアルゴリズムの2つの異なるバージョンを比較するのは非常に簡単です。
さらに、差分を非常に読みやすくし、テキストソースに使用される同様のツールを模倣するために、「フローストレッチ」を使用できます。
まとめましょう
- 結果を自動生成できますか-はい、簡単に
- 継続的に更新できますか-まったく問題ありません。
- 確定的でシンプルなレイアウト-はい、手動調整は必要ありません
- 単純なswitch-caseを視覚化できますか？-はい
- バージョン管理を処理し、違いを視覚化することを許可しますか-はい、可能です。ところで、3ウェイdiffも可能です。
代替ソリューションほとんどすべての複雑な言語で簡略化 [〜＃〜] dsl [〜＃〜] を導入できます。現在の言語の上に簡略化された言語を設計する方がはるかに簡単なはずです。
そうすることで、上記のすべてを事実上無料で入手できます。
多くの質問に感謝します:)
私の回答が役立つかどうかは、これを実行するスキルセットと利用可能な時間に依存するため、すべての人に役立つとは限りません。しかし、もしあなたがこの解決策をとることができれば、確かにいくつかの利点があります。
automatedユニットおよび/または統合テストを含むドキュメントスクリプトの基本的なテストハーネスを作成し、それらをリストとして提示するビジネスユーザー向けの「ビジネスルール」または「ユースケース」の例。
このアプローチには、いくつかの利点があります。
- あなたは彼らが正しいと確信することができます：あなたはそれらを実行することができます！
- 彼らはあなたを驚かせるかもしれません：あなたはスクリプトが完全に（まだ）理解していなかったので、あなたは緑であると期待するテストを書くかもしれませんが、それは赤になります（またはその逆）。
- これらは、変更が行われる場合に役立ちます。テストにより、1つの変更が別のシナリオを壊さないという確信が得られます。そのため、長期的には時間の節約にもなります。
欠点もいくつかあります。
- 「ビジネスルール」（テスト）のリストをビジネスユーザーにとって洞察力のあるものにするためには、多少の努力が必要です。視覚化（フローチャートなど）の方が理解しやすい場合があります。
- アプローチは正確であり、長期的には時間を節約できますが、時間に制限がある場合はあまり役に立ちません。例えば。ある朝、スクリプトを読み、午後にレポートを書く場合、このアプローチは機能しません。 あなたの質問では、あなたが目指している詳細と正確さのレベルを提供していませんが、それはそれに大きく依存します。
- このようなスクリプトの自動テストの作成に精通している必要があります。または、割り当てられた時間に学習時間を含めることができる必要があります。
- Unitテストは、スクリプトの構造に応じて、可能である場合と不可能である場合があります（または、少なくとも何らかのリファクタリングなしでは不可能です）。 （正直に言うと、「if/else構造の多く」のあるフォームはおそらくあまり適していません。）その場合、統合テストは引き続き可能です。
私が言ったように、このアプローチはすべての人のためではないかもしれません。ただし、このようにできる場合は、いくつかの素敵な特典が付いています。
このことを十分に考えた結果、プログラム全体の流れを誰もが理解しやすいものにしようとすると、プログラムコード自体よりも消費しにくくなると確信しています。 このスレッドに投稿されたすべてのコードの視覚化は、テキストの行よりも読みにくくなっています。
コードはすでに短く、要点があり、コンピュータに何をすべきかを伝えるためにコードを使用する理由です。もしプログラムの流れを表現するもっと簡単な方法があったら、そもそもそれが私たちがプログラミングに使うものだと思いませんか？
ただし、コードをナビゲートしやすくする方法はいくつかあります。
ステップ1：ステートメントを可能な限り線形にする
関数呼び出しまたはループで繰り返されるコード行を記述して、プログラム全体が変数宣言または条件付き割り当てのリストになるようにする方が明確です（デフォルトでは条件が真であり、IFステートメントが指定されていないときに割り当てが行われます）。
手順2：記号を単語に置き換える
Pseudocodeは少し読みやすいので、母国語を英語のようなものに変換してみてください。たとえば、セミコロンや中括弧を表示する必要はなく、&&のような論理演算子はANDとして読みやすくなります。フローチャートや表を作成しようとすると、ほとんどの場合、単純なテキスト行よりも読みにくくなります。
手順3：指示の長いリストを検索しやすくする
ユーザーが入力するときに変数の名前を強調表示します
一致しないコード行をリンクに折りたたみ、展開してクリックするとコンテキストを表示できます
このやり取りを改善するためにできることは他にもいくつかあります。
すべての条件付き変数割り当てを表示するまたはすべての変数宣言を表示するなどへのリンクを作成します。
各変数の開始値の入力を許可して、ユーザーが値がインラインでどのように変化するかを確認できるようにします
条件付き
IFステートメントを赤または緑で強調表示して、判別できる場合にtrueまたはfalseを示します
このソリューションがより多くのアイデアflowを取得することを願っています。 （しゃれ意図）
このタスクの難点の1つは、コードを読みやすくするために単純化すると、コードが単純な概念のみを表すようになることです。そのため、ユーザーの興味や関心に応じて、ユーザーが現在見ているものを調整する方法を備えたものが最良のフォーマットだと思います。
具体的には、プログラムの最も基本的な機能のみを外部層に表示し、選択可能な要素を持つフローチャートを作成できます。いずれかをクリックすると展開され、その要素の機能に対応する別のフローチャートが表示されます。
例：
外層
終了要素のクリック時
これがどれほど可能かはわかりませんが、プログラミングの性質上、プログラムのフロー全体と考えられる多くの結果/パスを非常に詳細に概念化することは非常に難しいようです。
基本的に、ドキュメント/プログラム/ Excelシート/「印刷された価格フィールドにVATが含まれるのはどのような条件ですか？」のような質問に答えられるものは何でも書きたいのですが。
私はこのアイデアが一番好きです。スタック交換のように、人々が必要な情報に個別にアクセスできるようにします。コンピューターではなく人間で実行するプログラムを再現するだけでもフローチャートは不可欠だと思います。そして、コンピュータにこの種の作業を行わせるのには十分な理由があります。
もちろん、あなたがそうすることに満足するだけでなく、人々にプログラムを理解してほしいと思っていると思います。プロセスを理解する人が増えると、プロジェクトの自律性と意思決定能力が失われる可能性があります。 bike shedding を参照してください。