Tips on writing a good documentation.pdf

‫ﻧﮑﺎﺗﻲ ﺑﺮﺍ ﻧﻮﺷﺘﻦ ﻣﺴﺘﻨﺪﺍﺕ ‪ ١‬ﺧﻮﺏ‬
‫ﻣﺴﺘﻨﺪﺍﺕ ﺩﺭ ﻭﺍﻗﻊ ﺟﺎ ﮔﺰﻳﻦ ﺗﺤﻮﻳﻞ ﺣﻀﻮﺭ ﻫﺴﺘﻨﺪ‪ .‬ﺩﺭ ﻧﺘﻴﺠﻪ ﺑﺎﻳﺪ ﻃﻮﺭ ﺑﺎﺷﻨﺪ ﮐﻪ ﺍﻭ ﹰﻻ ﺭﺍﺣﺖ ﻗﺎﺑﻞ‬
‫ﻓﻬﻢ ﺑﺎﺷﻨﺪ‪ ،‬ﺛﺎﻧﻴ ﹰﺎ ﻧﮑﺎﺕ ﮐﻠﻴﺪ ﻭ ﻧﺎﺑﺪﻳﻬﻲ ﮐﺎﺭ ﺷﻤﺎ ﺭﺍ ﺷﺎﻣﻞ ﺑﺎﺷﻨﺪ‪ .‬ﻓﺮﺽ ﮐﻨﻴﺪ ﻣﻲﺧﻮﺍﻫﻴﺪ ﭘﺮﻭﮊﻩﺍ ﮐﻪ‬
‫ﺍﻧﺠﺎﻡ ﺩﺍﺩﻩﺍﻳﺪ ﺭﺍ ﺑﻪ ﻃﻮﺭ ﺧﻼﺻﻪ ﺑﺮﺍ ﻳﮏ ﻧﻔﺮ ﻧﺎﻭﺍﺭﺩ ﺗﻮﺿﻴﺢ ﺩﻫﻴﺪ‪ .‬ﭼﻴﺰﻫﺎﻳﻲ ﮐﻪ ﺑﻪ ﺍﻭ ﻣﻲﮔﻮﺋﻴﺪ ﺭﺍ ﺑﺎﻳﺪ ﺩﺭ‬
‫ﻣﺴﺘﻨﺪﺍﺕ ﺑﻨﻮﻳﺴﻴﺪ ﻭ ﭼﻴﺰﻫﺎﻳﻲ ﮐﻪ ﺧﻮﺩﺵ ﺑﺪﻭﻥ ﻓﮑﺮ ﺯﻳﺎﺩ ﻣﻲﺗﻮﺍﻧﺪ ﺑﻔﻬﻤﺪ ﺭﺍ ﻻﺯﻡ ﻧﻴﺴﺖ‪.‬‬
‫ﻭ ﺿﻤﻨ ﹰﺎ ﻫﻢ ﺑﺮﺍ ﺩﺭﮎ ﺑﻬﺘﺮ ﻣﻮﺿﻮﻉ ﻭ ﻫﻢ ﺑﻴﺎﻥ ﺩﻗﻴﻖ ﺟﺰﺋﻴﺎﺕ‪ ،‬ﻣﺜﺎﻝ ﺯﺩﻥ ﺧﻴﻠﻲ ﻣﻲﺗﻮﺍﻧﺪ ﻣﻔﻴﺪ ﺑﺎﺷﺪ‪،‬‬
‫ﻣﺨﺼﻮﺻ ﹰﺎ ﺯﺩﻥ ﻣﺜﺎﻝﻫﺎ ﺧﺎﺹ‪.‬‬
‫‪٢‬‬
‫ﻼ ﺩﺭ ﻓﺎﺯ ﺳﻮﻡ ﭘﺮﻭﮊﻩ ﮐﺎﻣﭙﺎﻳﻠﺮ‪ ،‬ﺩﺭ ﻃﺮﺍﺣﻲ ﺟﺪﻭﻝ ﻧﻤﺎﺩﻫﺎ ﻧﮑﺎﺕ ﻧﺎﺑﺪﻳﻬﻲﺍ ﮐﻪ ﻭﺟﻮﺩ ﺩﺍﺷﺖ ﺍﻳﻦﻫﺎ‬
‫ﻣﺜ ﹰ‬
‫ﺑﻮﺩ‪ :‬ﺳﺎﺧﺘﺎﺭ ﮐﻠﻲ ﺟﺪﻭﻝ‪ ،‬ﻳﻌﻨﻲ ﺍﺯ ﭼﻪ ﮐﻼﺱﻫﺎﻳﻲ ﺍﺳﺘﻔﺎﺩﻩ ﮐﺮﺩﻩﺍﻳﺪ ﻭ ﻧﻘﺶ ﺁﻥﻫﺎ ﭼﻴﺴﺖ؟ ﺟﺰﺋﻴﺎﺕ‬
‫ﻧﺎﺑﺪﻳﻬﻲ ﺍﻳﻦﻫﺎ ﻫﺴﺘﻨﺪ‪ :‬ﭼﮕﻮﻧﮕﻲ ﭘﻴﺎﺩﻩﺳﺎﺯ ‪ extends‬ﻭ ﭼﮕﻮﻧﮕﻲ ﻧﮕﻪﺩﺍﺭ ﺁﺭﮔﻮﻣﺎﻥﻫﺎ ﺗﻮﺍﺑﻊ‪.‬‬
‫ﻣﺜﺎﻝ ﺧﻮﺏ‪:‬‬
‫‪.۱‬‬
‫‪ MethodTable‬شامل اجزاي زیر است ‪:‬‬
‫ یك >‪ HashTable<String , String‬به نام ‪ allVars‬است که به ازاي هر متغیر تعریف شده‬‫در کالس ‪ ،‬نام آن به همراه ‪ type‬آن را به ‪ allVars‬اضافه ميکنیم ( ‪ .‬مولفه ی اول مربوط به‬
‫نام و مولفه ی دوم مربوط به نوع متغیر است(‪.‬‬
‫یک >‪ HashTable<String , String‬به نام ‪ allParams‬است که به ازاي هر ‪parameter‬‬‫تعریف شده در کالس‪ ،‬نام آن به همراه ‪ type‬آن را به ‪ allParams‬اضافه ميکنیم‪.‬‬
‫ و همین طور یک >‪ ArrayList<String‬به نام ‪ params‬که ترتیب پارامترها را در خود نگه‬‫میدارد ‪ .‬وقتی متدی صدا زده می شود‪ ،‬به کمک این لیست درست بودن ترتیب پارامترهای‬
‫داده شده به آن را چک میکنیم ‪.‬‬
‫ ‪ Parent‬که نام کالسي که ‪ method‬در آن تعریف شده را در خود نگه ميدارد‪.‬‬‫‪ returnType -‬که براي هر تابع مشخص شده را نگاه میدارد‪.‬‬
‫ﻣﺜﺎﻝ ﺑﺪ‪:‬‬
‫‪ .۱‬در این فاز برای ساختن جدول سمبلها از کالس ‪ SymbolTableBuilder‬استفاده میشود‪.‬‬
‫این کالس گرههای درخت را پرمایش کرده و اسم و تایپ سمبلها را استخراج میکند‪ .‬این‬
‫‪documentation‬‬
‫‪symbol table‬‬
‫‪1‬‬
‫‪2‬‬
‫کالس از سه کالس اصلی ‪ classSymbol‬و ‪ methodSymbol‬و ‪ fieldSymbol‬برای شناسایی‬
‫سمبل "کالس"‪"،‬متد" و "فیلد"های کالسهای ‪ miniJava‬کمک میگیرد‪ .‬در همین مرحله اگر‬
‫اسم دو کالس در برنامه یکی باشد و یا اینکه دو متد همنام یا فیلد همنام داشتهباشیم‪،‬‬
‫‪ semanticError‬دادهمیشود و بقیهی مراحل انجام نمیشود‪ ← .‬ﻓﺎﻗﺪ ﺟﺰﺋﻴﺎﺕ ﮐﺎﻓﻲ‬
‫‪ .۲‬هر عضو سیمبل تیبل ‪ ۴‬عضو دارد ‪ ،‬اولی نشاندهنده ی کالسی است که در آن هستیم ‪،‬‬
‫دومی نشان دهنده ی تابعی که در آن هستیم ‪ ،‬سومی نام این سیمبل است و آخری‬
‫تایپ آن‪) .‬البته در مواقعی مانند وقتی که سیمبل یک کالس است ‪ ،‬تفاوتهای اندکی‬
‫وجود دارد( ← ﻓﺎﻗﺪ ﺟﺰﺋﻴﺎﺕ ﮐﺎﻓﻲ‬
‫دربارهی جزئیات انجام ‪:type-checking‬‬
‫ﻣﺜﺎﻝ ﺑﺪ‪:‬‬
‫‪ .۱‬طریقهی تایپ چکینگ ‪ ،‬کاملن معمولی است و به صورتِ بازگشتی روی درختِ برنامه‬
‫انجام می شود ‪ .‬مثال برای یک عبارت جمع ‪ ،‬ابتدا چک می شود که تایپ سمت چپ‬
‫اینتیجر باشد ‪ ،‬سپس چک می شود که تایپ سمت راست اینتیجر باشد و در انتها هم‬
‫تایپ اینتیجر به عنوانِ تایپ کلی عبارت برگردانده می شود ‪ ← .‬ﻓﺎﻗﺪ ﺟﺰﺋﻴﺎﺕ ﮐﺎﻓﻲ‬
‫‪ .۲‬تابع ‪ visit‬را صدا می زنیم که این تابع کار ‪ type checking‬را انجام می دهد که در این تابع‬
‫‪ duplication‬را نیز ‪ check‬می کنیم و هم چنین اینکه آیا متغیر تعریف شده یا نه ‪ ،‬یا اینکه‬
‫متغیر جز فیلد های کالس هست یا نه ‪ .‬هم چنین برای ‪ method call ، check‬ها ‪field ،‬‬
‫‪ args‬را که در ‪ traverse‬ساخته بودیم با ‪ ، type‬پارامترهای ورودی چک می کنیم ← ﻓﺎﻗﺪ‬
‫ﺟﺰﺋﻴﺎﺕ ﮐﺎﻓﻲ‬
‫‪ .۳‬در زمان ‪ Type ،Parse‬متغیرها به صورت ‪ L-Attribute‬در گرههای درخت منتشر میشوند تا‬
‫نهایتاً در ‪ Pass‬مربوطه به ‪ Type Check‬بر مبنای ‪ Attribute‬های تولید شده کنترلهای الزم‬
‫صورت گیرند‪ ← .‬ﻓﺎﻗﺪ ﺟﺰﺋﻴﺎﺕ ﮐﺎﻓﻲ‬
‫ﻣﺜﺎﻝ ﺧﻮﺏ‪:‬‬
‫‪ .۱‬برای عمل ‪ Type-Checking‬الزم است یک بار درخت را طی کنیم‪ .‬برای این کار برای هر ‪node‬‬
‫درخت به جز ‪Expression‬ها یک متد با نام ‪ typeCheck‬تعریف شده است که در صورت‬
‫وجود مشکل یک ‪ Exception‬از نوع ‪ TypeException‬را ‪ Throw‬میکند‪ .‬برای‬
‫‪Expression‬ها نیز یک متد با نام ‪ getType‬تعریف شده است که ‪ Type‬آن ‪ Expression‬را‬
‫برمیگرداند و در صورت وجود مشکل یک ‪ Exception‬از نوع ‪ TypeException‬را ‪Throw‬‬
‫میکند‪ .‬علت اینکه برای ‪Expression‬ها متد متفاوتی تهیه شده است آن است که‬
‫‪Expression‬ها دارای ‪ Type‬هستند اما سایر ‪node‬های درخت ‪ Type‬ندارند‪ .‬در طی کردن‬
‫درخت از ‪ attribute‬استفاده نشده است‪.‬‬
‫‪ .۲‬برای این کار از کالس ‪ TypeChecker‬که با توجه به الگوی ‪ Visitor‬پیادهسازی شده‪ ،‬استفاده‬
‫میشود‪.‬‬
‫تابع )‪arg‬‬
‫‪ ،visit(node,‬برای‬
‫‪ node‬های‬
‫عبارت )‪،ExpressionNode‬‬
‫‪ IdentifierNode‬و ‪ Node‬های مربوط به جمع‪ ،‬ضرب و‪ (...‬نوع آنها را بازمیگرداند‪ .‬بدین‬
‫وسیله عملیات ‪ Type Checking‬بهسادگی قابل انجام است‪ .‬مثال در فراخوانی )(‪ visit‬برای‬
‫یک ‪ Node‬مقایسه‪ ،‬ابتدا دو طرف این عملگر )(‪ visit‬میشوند‪ .‬نوع آنها باید ‪ int‬باشد‪.‬‬
‫سپس این تابع نوع ‪ boolean‬را به خروجی میدهد‪.‬‬